Skip to content

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

33.5 KB
Raw Blame
/**
 * Pipeline — Comic page renders + panel prompt refine (#2531)
 *
 * Comic-page prompt composition, page/panel image enqueue + persist, the
 * per-page image-to-image refine, the generic visual-image enqueue, and the
 * consistency-reference resolvers. Extracted from the former monolithic
 * `visualStages.js`; shares plumbing via `./visualStageHelpers.js`.
 */

import { updateStage, updateStageWithLatest, assertStageUnlocked, VISUAL_STAGE_IDS } from './issues.js';
import { resolveGalleryImage } from '../../lib/fileUtils.js';
import { buildComicPagesOwner, slotKeyForVariant } from './owners.js';
import { ServerError } from '../../lib/errorHandler.js';
import {
  buildCharByKey, matchSceneCharacters, matchCharactersInText,
  matchPlacesInText, matchObjectsInText,
} from '../../lib/scenePrompt.js';
import { flattenCanonDescriptorFragments, richCanonDescriptorFragments } from '../../lib/canonPrompt.js';
import { sameComicScene } from '../../lib/comicScriptParser.js';
import { runPromptRefine, runImagePromptCandidates } from './refineHelpers.js';
import {
  applyWorldStyle, stackStyle, formatBalloon, loadBibleContext, resolveMode,
  resolveVariant, resolveProofInitImage, resolvePageReferenceImage,
  REFERENCE_PAGE_DEFAULT_STRENGTH, PROOF_AS_BASE_DEFAULT_STRENGTH,
  REFINE_RENDER_DEFAULT_STRENGTH, applyCharacterLorasToRender, loraRenderOptions,
  enqueueImageJob, buildRenderSlot, composeVisualPrompt, seriesBibleCtx,
  issueCtx, neighborText, loadRefineContext, assertCharacterAppearancesResolve,
  persistRenderOrCancel,
} from './visualStageHelpers.js';

// Resolve the `referencePage` option ('prior' | 'next' | <0-based index>) to a
// concrete page index, or null when unset. Pure + bounds-checked against the
// page count; throws a clear 400 for an out-of-range request (prior on page 1,
// next on the last page, or an explicit index that doesn't exist).
export function resolveReferencePageIndex(referencePage, pageIndex, pageCount) {
  if (referencePage == null) return null;
  let target;
  if (referencePage === 'prior') target = pageIndex - 1;
  else if (referencePage === 'next') target = pageIndex + 1;
  else if (Number.isInteger(referencePage)) target = referencePage;
  else throw new ServerError(`Invalid referencePage: ${referencePage}`, { status: 400, code: 'PIPELINE_COMIC_REFERENCE_BAD' });
  if (target === pageIndex) {
    throw new ServerError('A page cannot be its own consistency reference', { status: 400, code: 'PIPELINE_COMIC_REFERENCE_SELF' });
  }
  if (target < 0 || target >= pageCount) {
    throw new ServerError(
      `Consistency reference page ${target + 1} is out of range (have ${pageCount} page${pageCount === 1 ? '' : 's'})`,
      { status: 400, code: 'PIPELINE_COMIC_REFERENCE_RANGE' },
    );
  }
  return target;
}

// Auto-pick a consistency reference for a fresh page render: the immediately
// prior page, but ONLY when it shares this page's scene AND has already been
// rendered. This is the default when the caller doesn't name an explicit
// `referencePage` — so a continuing scene keeps its incidental characters and
// environment consistent page-to-page, while a scene boundary renders fresh
// (the "don't reference the prior page across a scene cut" rule). Pure +
// soft: returns null (rather than throwing) when there's no prior page, the
// scenes differ, scene markers are absent (legacy scripts → no auto-chain), or
// the prior page has no image yet — auto-chaining is a best-effort nicety, not
// a hard requirement like an explicitly requested reference.
export function resolveAutoReferenceIndex(pages, pageIndex) {
  const cur = pages?.[pageIndex];
  const prior = pages?.[pageIndex - 1];
  if (!cur || !prior) return null;
  if (!sameComicScene(prior, cur)) return null;
  const hasImage = !!(prior.finalImage?.filename || prior.proofImage?.filename);
  return hasImage ? pageIndex - 1 : null;
}

// Resolve which init image (if any) a comic-page render should use, applying
// the three precedence tiers in order:
//   1. EXPLICIT `referencePage` ('prior' | 'next' | <index>) — strongest
//      intent; bounds-checked (throws on an out-of-range request). `'none'`
//      opts out of the AUTO tier (no cross-page reference, even mid-scene).
//   2. PROOF-AS-BASE — a final-variant upscale off this page's own proof. Beats
//      auto so "Final from proof" still preserves panel layout. Orthogonal to
//      `'none'` (it's a self-upscale, not a sibling reference), so it still
//      applies when the user picked 'none' but left the proof-as-base box on.
//   3. AUTO — chain off the prior page when it shares this page's scene and is
//      already rendered; a scene boundary (or absent scene markers) skips it.
// Pure; returns the chosen tier so the caller picks the init image + strength
// and logs it. `autoReference` is true only when the AUTO tier supplied the
// page (so callers can distinguish it from an explicit reference).
export function resolveComicPageReference({ referencePage, useProofAsBase, variant, pages, pageIndex }) {
  const explicitOff = referencePage === 'none';
  const wantsExplicit = !explicitOff && referencePage != null && referencePage !== 'auto';
  const explicitIndex = wantsExplicit
    ? resolveReferencePageIndex(referencePage, pageIndex, pages.length)
    : null;
  const fromProof = explicitIndex == null && variant === 'final' && useProofAsBase === true;
  const autoIndex = (explicitIndex == null && !fromProof && !explicitOff)
    ? resolveAutoReferenceIndex(pages, pageIndex)
    : null;
  const referencePageIndex = explicitIndex != null ? explicitIndex : autoIndex;
  return {
    referencePageIndex,
    fromReference: referencePageIndex != null,
    autoReference: referencePageIndex != null && explicitIndex == null,
    fromProof,
  };
}

export function composeComicPagePrompt({
  series, world, page, pageNumber, extraStyle = '',
  matchedCharacters = [], matchedPlaces = [], matchedObjects = [],
  // entryId/ingredientId → trained-LoRA trigger word (see
  // applyCharacterLorasToRender). Passed as a map so this compose stays pure.
  loraTriggerByKey = null,
}) {
  const panels = Array.isArray(page?.panels) ? page.panels : [];
  if (panels.length === 0) return '';

  // Placed AFTER the layout clause: diffusion models weight earlier tokens
  // more heavily, and the page-shape instruction has to claim that position.
  // A character with a trained LoRA gets its trigger word parenthesized
  // after the name — the token the adapter binds the identity to.
  const featuring = (matchedCharacters || [])
    .map((c) => ({
      name: c.name,
      trigger: loraTriggerByKey?.get(c.id) || loraTriggerByKey?.get(c.ingredientId) || null,
      desc: (c.physicalDescription || c.description || '').trim(),
    }))
    .filter((c) => c.name && c.desc)
    .map((c) => `${c.name}${c.trigger ? ` (${c.trigger})` : ''}: ${c.desc}`)
    .join('; ');

  // Place baseline: pull the full RICH descriptor set per matched place
  // (description / Palette / Era / Weather / recurringDetails). Same shared
  // helper that drives buildScenePrompt's placeFrags + synthesizeCanonPrompt's
  // body, so comic-page renders pick up the same era/weather/atmosphere cues
  // diffusion models weight for lighting + period dress. Multi-place per page
  // is supported (a single page can span more than one location).
  const placesClause = (matchedPlaces || [])
    .map((p) => {
      const body = flattenCanonDescriptorFragments(richCanonDescriptorFragments('place', p));
      const head = p.name ? `${p.name}:` : '';
      return [head, body].filter(Boolean).join(' ');
    })
    .filter(Boolean)
    .join(' | ');

  // Notable objects/props/vehicles cited in the prose. Keeps signature props
  // (e.g. "the brass key", "Wren's sloop") visually canonical across pages.
  const notable = (matchedObjects || [])
    .map((o) => ({ name: o.name, desc: (o.description || '').trim() }))
    .filter((o) => o.name && o.desc)
    .map((o) => `${o.name}: ${o.desc}`)
    .join('; ');

  // Append a sentence-terminator unless the source text already ends in one —
  // prose extracted from a script often carries its own `.`, `!`, or `?`, and
  // double-punctuating like "...sunstreaming in.." is noisy in prompts. The
  // optional trailing `"` covers the dialogue/caption case where we wrap the
  // text in quotes — `KESSA: "...away."` should NOT become `KESSA: "...away.".`.
  const endPunct = (s) => /[.!?]"?$/.test(s) ? s : `${s}.`;

  const panelLines = panels.map((p, i) => {
    const idx = i + 1;
    const desc = (p.description || '').trim() || 'continuation of previous beat';
    const parts = [`Panel ${idx}: ${endPunct(desc)}`];
    if (p.caption && p.caption.trim()) parts.push(`Narration caption box reads: "${endPunct(p.caption.trim())}"`);
    if (Array.isArray(p.dialogue) && p.dialogue.length > 0) {
      // Format each dialogue line as `Speech balloon reads: "<text>" (spoken
      // by NAME[, balloon style: <hint>])`. Lettered content (the quoted
      // text) leads so the diffusion model anchors on it; speaker + style
      // hints trail as attribution. The previous `NAME (MODIFIER): "text"`
      // shape (Marvel/DC script convention) was being lettered verbatim
      // INTO balloons by the image model — including the speaker name and
      // parentheticals like "(EARPIECE)". Dropping speaker into the
      // attribution slot and translating common parentheticals to balloon
      // styling hints (jagged for radio/earpiece, dashed for whisper, cloud
      // for thought) preserves the artistic intent without leaking labels
      // into the lettered text.
      const dlg = p.dialogue
        .map((d) => formatBalloon(d.character, d.line))
        .filter(Boolean)
        .join(' ');
      if (dlg) parts.push(dlg);
    }
    if (p.sfx && p.sfx.trim()) parts.push(`SFX lettering: ${endPunct(p.sfx.trim())}`);
    return parts.join(' ');
  });

  const styleStack = stackStyle(series, extraStyle);
  const styleClause = styleStack ? ` Art style: ${styleStack}.` : '';
  const seriesClause = series?.name ? ` from the series "${series.name}"` : '';

  const layout = `A single full printable comic book page${seriesClause}, page ${pageNumber}. Render a balanced multi-panel comic page layout with ${panels.length} clearly bordered panel${panels.length === 1 ? '' : 's'} arranged for left-to-right, top-to-bottom reading. Include lettered speech balloons for dialogue, rectangular narration boxes for captions, and stylized SFX where indicated. **Balloon lettering rule: each speech balloon contains ONLY the quoted text shown after "Speech balloon reads:". NEVER letter the speaker's name, role, or any parenthetical attribution (e.g. "(EARPIECE)", "(WHISPERED)", "(OFF-PANEL)") inside the balloon — those are tail-direction and balloon-styling cues for the artist, not lettered content.** Each panel must be visually distinct, with consistent character designs across panels.${styleClause}`;
  const featuringClause = featuring ? `\n\nFeaturing — ${featuring}` : '';
  const placeClause = placesClause ? `\n\nSetting — ${placesClause}` : '';
  const notableClause = notable ? `\n\nNotable — ${notable}` : '';

  return applyWorldStyle(`${layout}${featuringClause}${placeClause}${notableClause}\n\n${panelLines.join('\n\n')}`, world, series);
}

/**
 * Enqueue a full-comic-page image render. Builds a structured page-level
 * prompt from `issue.stages.comicPages.pages[pageIndex].panels[]` and hands
 * it to the image-gen queue. Caller records the returned jobId on the
 * appropriate variant slot (`pages[pageIndex].proofImage` /
 * `pages[pageIndex].finalImage`) based on `options.target`.
 *
 * When `options.useProofAsBase` is set and target='final', resolves the
 * page's existing proof image and passes it as initImagePath so the local
 * i2i runner can preserve panel layout while upscaling.
 *
 * Returns { jobId, mode, prompt, pageIndex, variant, fromProof }.
 */
export async function enqueueVisualComicPage(issueId, options = {}) {
  const pageIndex = Number(options.pageIndex);
  if (!Number.isInteger(pageIndex) || pageIndex < 0) {
    throw new ServerError('pageIndex must be a non-negative integer', {
      status: 400, code: 'PIPELINE_COMIC_PAGE_BAD_INDEX',
    });
  }
  const { issue, settings, series, world, canon } = await loadBibleContext(issueId);
  assertStageUnlocked(issue, 'comicPages');
  const pages = Array.isArray(issue.stages?.comicPages?.pages) ? issue.stages.comicPages.pages : [];
  const page = pages[pageIndex];
  if (!page) {
    throw new ServerError(`page index ${pageIndex} out of range (have ${pages.length})`, {
      status: 404, code: 'PIPELINE_COMIC_PAGE_NOT_FOUND',
    });
  }
  if (!Array.isArray(page.panels) || page.panels.length === 0) {
    throw new ServerError('page has no panels — add at least one panel description before rendering', {
      status: 400, code: 'PIPELINE_COMIC_PAGE_NO_PANELS',
    });
  }

  const variant = resolveVariant(options.target);

  // Consistency reference: pass an already-rendered page as the init image so a
  // continuing scene keeps its incidental, un-described characters and
  // environment consistent (the "two newlyweds drift between pages" problem).
  // The three-tier precedence (explicit > proof-as-base > auto-within-scene)
  // lives in resolveComicPageReference.
  const { referencePageIndex, fromReference, autoReference, fromProof } = resolveComicPageReference({
    referencePage: options.referencePage,
    useProofAsBase: options.useProofAsBase,
    variant, pages, pageIndex,
  });
  const initImagePath = fromReference
    ? resolvePageReferenceImage(pages[referencePageIndex], `page ${referencePageIndex + 1}`)
    : fromProof
      ? resolveProofInitImage(page.proofImage, `page ${pageIndex + 1}`)
      : null;
  const initImageStrength = fromReference
    ? (Number.isFinite(options.initImageStrength) ? options.initImageStrength : REFERENCE_PAGE_DEFAULT_STRENGTH)
    : fromProof
      ? (Number.isFinite(options.initImageStrength) ? options.initImageStrength : PROOF_AS_BASE_DEFAULT_STRENGTH)
      : undefined;
  // Resolved AFTER the init image, so an i2i render skips edit-incapable
  // backends rather than resolving to one that rejects the job in the queue
  // (#3243).
  const mode = resolveMode(options, settings, series);

  // Build a free-text haystack from every panel's prose (description +
  // caption + sfx). Dialogue lines feed character matching via CAPS names
  // separately because the parser already structures them.
  const proseHaystack = page.panels
    .flatMap((p) => [p.description, p.caption, p.sfx])
    .filter(Boolean)
    .join('\n');
  const dialogueNames = page.panels.flatMap((p) =>
    (p.dialogue || []).map((d) => d.character).filter(Boolean),
  );

  // Characters: union of (a) dialogue CAPS speakers and (b) anyone named in
  // panel prose. Deduplicates on id/name inside the matchers. Canon is read
  // from `canon` (Phase B helper) which prefers the linked universe and
  // falls back to series arrays for pre-migration data.
  const charByKey = buildCharByKey(canon.characters);
  const fromDialogue = matchSceneCharacters(dialogueNames, charByKey);
  const fromProse = matchCharactersInText(proseHaystack, canon.characters);
  const seenCharKeys = new Set();
  const matchedCharacters = [...fromDialogue, ...fromProse].filter((c) => {
    const k = c.id || c.name;
    if (seenCharKeys.has(k)) return false;
    seenCharKeys.add(k);
    return true;
  });

  // Places + objects: text-match against the panel prose. Codex can't take
  // reference images, so rich text descriptions in the prompt are how we
  // keep environments and signature props visually consistent page-to-page.
  const matchedPlaces = matchPlacesInText(proseHaystack, canon.places);
  const matchedObjects = matchObjectsInText(proseHaystack, canon.objects);

  // composeComicPagePrompt only returns '' when panels.length === 0, which is
  // already rejected above. The "(continuation of previous beat)" placeholder
  // covers panels with no description, so the prompt is non-empty by here.
  const { loras: characterLoras, triggerByKey, selectedModel } = await applyCharacterLorasToRender({
    matchedCharacters, mode, options, settings,
  });

  const prompt = composeComicPagePrompt({
    series, world, page, pageNumber: pageIndex + 1,
    extraStyle: options.extraStyle || '',
    matchedCharacters, matchedPlaces, matchedObjects,
    loraTriggerByKey: triggerByKey,
  });

  const jobId = await enqueueImageJob({
    prompt, world, settings, mode, series,
    options: { ...options, initImagePath, initImageStrength, ...loraRenderOptions(characterLoras) },
    selectedModel,
    owner: buildComicPagesOwner({ issueId, target: 'page', pageIndex, variant }),
    logLine: `📄 Pipeline comic page — issue=${issueId.slice(0, 8)} page=${pageIndex + 1} panels=${page.panels.length} variant=${variant}${fromProof ? ' (from proof)' : ''}${fromReference ? ` (${autoReference ? 'auto-ref' : 'ref'} page ${referencePageIndex + 1})` : ''}`,
  });
  return { jobId, mode, prompt, pageIndex, variant, fromProof, fromReference, autoReference, referencePageIndex };
}

/**
 * Splice an in-flight render slot onto
 * `stages.comicPages.pages[pageIndex].{proofImage|finalImage}` through
 * `updateStageWithLatest` (the serialized issue write tail) so a concurrent
 * page edit or sibling render that wrote between the enqueue and this persist
 * can't be reverted by a stale snapshot. Shared by `renderComicPage` and
 * `refineComicPageRender` — the filename hook only attaches the completed
 * image when the target slot already carries the returned jobId (the reason
 * this write must live behind the shared entry points, not only in the route).
 *
 * The job is enqueued BEFORE this write, so a rejected write (the page was
 * deleted between the caller's read and here) would leave the job queued with
 * nothing referencing it — `persistRenderOrCancel` cancels that orphan and
 * rethrows (#3413).
 *
 * Returns { issue, stage } from the write tail.
 */
async function persistComicPageSlot(issueId, pageIndex, { variant, jobId, prompt, width, height, fromProof }) {
  const slotKey = slotKeyForVariant(variant);
  const slotRecord = buildRenderSlot({ slotKey, jobId, prompt, width, height, fromProof });
  return persistRenderOrCancel(jobId, () => updateStageWithLatest(issueId, 'comicPages', (currentStage) => {
    const currentPages = Array.isArray(currentStage?.pages) ? currentStage.pages : [];
    if (!currentPages[pageIndex]) {
      throw new ServerError(
        `pageIndex ${pageIndex} out of range — comicPages has ${currentPages.length} page${currentPages.length === 1 ? '' : 's'}`,
        { status: 404, code: 'PIPELINE_COMIC_PAGE_NOT_FOUND' },
      );
    }
    const nextPages = [...currentPages];
    nextPages[pageIndex] = { ...currentPages[pageIndex], [slotKey]: slotRecord };
    return { status: 'edited', pages: nextPages };
  }), 'comic page slot');
}

/**
 * Enqueue + persist a full comic-page render in ONE service call — the shared
 * entry point behind both the route handler and the CDO orchestrator tool
 * (#2241, mirroring the #2234 cover treatment). The bare `enqueueVisualComicPage`
 * only queues the job; the filename hook attaches the completed render ONLY if
 * `pages[pageIndex]`'s active variant slot already carries the returned jobId,
 * and that slot write used to live in the route handler. Extracting it here
 * means the orchestrator gets orchestrated pages instead of silently dropping
 * them. `options` mirrors the route body (target/useProofAsBase/referencePage,
 * width/height, mode, …).
 *
 * Returns the enqueue result plus the persisted { issue, stage }.
 */
export async function renderComicPage(issueId, options = {}) {
  const result = await enqueueVisualComicPage(issueId, options);
  const { issue, stage } = await persistComicPageSlot(issueId, result.pageIndex, {
    variant: result.variant, jobId: result.jobId, prompt: result.prompt,
    width: options.width, height: options.height, fromProof: result.fromProof,
  });
  return { ...result, issue, stage };
}

/**
 * AI prompt-refine + image-to-image re-render for a SMALL correction to an
 * already-rendered comic page (issue #1534). Unlike `enqueueVisualComicPage`
 * (which composes a fresh prompt from the page's panels and re-renders from
 * source), this:
 *
 *   1. Takes the page's CURRENT render prompt (stored on the proof/final slot)
 *      plus the user's free-text instruction, and asks the LLM to ADJUST that
 *      prompt to reflect the instruction — never regenerating from the comic
 *      script. Everything not called out by the instruction is preserved.
 *   2. Re-renders image-to-image using the page's EXISTING output image as the
 *      init base at a low denoise, so the panel layout / composition / lettering
 *      survive and only the requested change moves.
 *
 * The base image (and the slot the refined render lands back on) is the page's
 * final render when present, else its proof; `options.target` forces a variant.
 * This is the common "page is mostly right, needs a tweak" case where a full
 * re-render from the script would throw away everything good about the current
 * output.
 *
 * Returns { jobId, mode, prompt, pageIndex, variant, changes, runId, providerId }.
 */
export async function refineComicPageRender(issueId, options = {}) {
  const pageIndex = Number(options.pageIndex);
  if (!Number.isInteger(pageIndex) || pageIndex < 0) {
    throw new ServerError('pageIndex must be a non-negative integer', {
      status: 400, code: 'PIPELINE_COMIC_PAGE_BAD_INDEX',
    });
  }
  const instruction = (options.instruction || '').trim();
  if (!instruction) {
    throw new ServerError('instruction is required — describe the small change to apply', {
      status: 400, code: 'PIPELINE_COMIC_REFINE_NO_INSTRUCTION',
    });
  }

  const { issue, settings, series, world } = await loadBibleContext(issueId);
  assertStageUnlocked(issue, 'comicPages');
  const pages = Array.isArray(issue.stages?.comicPages?.pages) ? issue.stages.comicPages.pages : [];
  const page = pages[pageIndex];
  if (!page) {
    throw new ServerError(`page index ${pageIndex} out of range (have ${pages.length})`, {
      status: 404, code: 'PIPELINE_COMIC_PAGE_NOT_FOUND',
    });
  }

  // Mirror the client's getProofSlot: a legacy page (pre proof/final split)
  // stores its render at the record root (imageJobId/filename/prompt), and the
  // UI surfaces that as the proof slot — so it shows the Refine control. Resolve
  // the same legacy shape here, otherwise refining a page whose only render is
  // legacy would 400 with NO_RENDER even though the UI shows it as rendered. The
  // refined render lands on the proofImage slot, upgrading the record into the
  // new shape (same as a /render of a legacy page).
  const legacyProofSlot = (!page.proofImage?.filename && (page.imageJobId || page.filename))
    ? { filename: page.filename || null, prompt: page.prompt || null }
    : null;

  // Resolve which rendered variant to refine: an explicit target wins; else
  // prefer the final render, falling back to the proof. The refined render
  // lands back on that SAME slot (the user is correcting that image).
  const variant = options.target
    ? resolveVariant(options.target)
    : (page.finalImage?.filename ? 'final' : 'proof');
  const baseSlot = variant === 'final'
    ? page.finalImage
    : (page.proofImage?.filename ? page.proofImage : legacyProofSlot);
  const baseFilename = baseSlot?.filename;
  if (!baseFilename) {
    throw new ServerError(
      `Cannot refine page ${pageIndex + 1}'s ${variant} render: it has no rendered image yet — render the page first.`,
      { status: 400, code: 'PIPELINE_COMIC_REFINE_NO_RENDER' },
    );
  }
  // The stored slot prompt is what we adjust — refusing to fall back to a
  // recomposed-from-script prompt is the whole point (a surgical edit, not a
  // redraw). A legacy slot without a persisted prompt must be re-rendered once
  // through `/render` (which stamps the prompt) before it can be refined.
  const currentPrompt = (baseSlot.prompt || '').trim();
  if (!currentPrompt) {
    throw new ServerError(
      `Cannot refine page ${pageIndex + 1}'s ${variant} render: its stored render prompt is missing — re-render the page first.`,
      { status: 400, code: 'PIPELINE_COMIC_REFINE_NO_PROMPT' },
    );
  }
  const initImagePath = resolveGalleryImage(baseFilename, { mustExist: false });
  if (!initImagePath) {
    throw new ServerError(
      `Existing page image path escaped the gallery for page ${pageIndex + 1}: ${baseFilename}`,
      { status: 400, code: 'PIPELINE_COMIC_REFINE_NOT_FOUND' },
    );
  }

  // Ask the LLM to apply the instruction to the existing prompt. resultField
  // 'prompt' + runPromptRefine's validation guarantees a non-empty string back;
  // `changes` is the short "what I changed" bullet list the UI surfaces.
  const { refined, changes, runId, providerId } = await runPromptRefine({
    templateName: 'pipeline-comic-page-refine-render',
    variables: {
      series: seriesBibleCtx(series),
      issue: issueCtx(issue),
      pageNumber: pageIndex + 1,
      currentPrompt: currentPrompt.slice(0, 16_000),
      instruction: instruction.slice(0, 2000),
    },
    options,
    source: 'pipeline-comic-page-refine-render',
    logTag: `Pipeline comic page refine — issue=${issueId.slice(0, 8)} page=${pageIndex + 1} variant=${variant}`,
  });

  // A refine render always redraws from `initImagePath`, so it is unconditionally
  // an edit — edit-incapable backends are skipped (#3243).
  const mode = resolveMode(options, settings, series);
  const initImageStrength = Number.isFinite(options.initImageStrength)
    ? Math.min(Math.max(options.initImageStrength, 0), 1)
    : REFINE_RENDER_DEFAULT_STRENGTH;

  const jobId = await enqueueImageJob({
    prompt: refined, world, settings, mode, series,
    options: { ...options, initImagePath, initImageStrength },
    owner: buildComicPagesOwner({ issueId, target: 'page', pageIndex, variant }),
    logLine: `🪄 Pipeline comic page refine — issue=${issueId.slice(0, 8)} page=${pageIndex + 1} variant=${variant} strength=${initImageStrength}`,
  });
  const { issue: persistedIssue, stage } = await persistComicPageSlot(issueId, pageIndex, {
    variant, jobId, prompt: refined, width: options.width, height: options.height,
  });
  return { jobId, mode, prompt: refined, pageIndex, variant, changes, runId, providerId, issue: persistedIssue, stage };
}

/**
 * Enqueue one image render for a pipeline issue's visual stage. The caller
 * records the returned jobId on the issue's stage artifact list
 * (e.g. stages.comicPages.pages[i].panels[j].imageJobId).
 *
 * Returns { jobId, mode, prompt }.
 */
export async function enqueueVisualImage(issueId, stageId, options = {}) {
  if (!VISUAL_STAGE_IDS.includes(stageId)) {
    throw new ServerError(`not a visual stage: ${stageId}`, {
      status: 400, code: 'PIPELINE_VISUAL_BAD_STAGE',
    });
  }
  const { issue, settings, series, world, canon } = await loadBibleContext(issueId);
  assertStageUnlocked(issue, stageId);
  // Resolve wardrobe picks against canon at the request boundary — a dangling
  // characterId/wardrobeId is a client/state bug worth a 400, not the silent
  // drop buildScenePrompt would otherwise apply.
  assertCharacterAppearancesResolve(options.characterAppearances, canon.characters);
  const mode = resolveMode(options, settings, series);
  // Match on description + slugline so the featured-character set (and thus
  // which wardrobe picks apply) stays consistent with the scene-video / shot
  // paths and the storyboards picker UI — all of which match both fields.
  const matchedCharacters = matchCharactersInText(
    `${options.description || ''} ${options.slugline || ''}`,
    canon.characters,
  );
  const composedPrompt = composeVisualPrompt({
    series,
    description: options.description,
    slugline: options.slugline,
    extraStyle: options.extraStyle || '',
    matchedCharacters,
    world,
    canon,
    // Storyboard scene renders thread the scene's wardrobe picks through the
    // generic visual-image route, which has no scene index to look them up.
    characterAppearances: options.characterAppearances,
  });
  if (!composedPrompt) {
    throw new ServerError('visual prompt is empty (no description, no style)', {
      status: 400, code: 'PIPELINE_VISUAL_EMPTY_PROMPT',
    });
  }

  const { loras: characterLoras, selectedModel } = await applyCharacterLorasToRender({
    matchedCharacters, mode, options, settings,
  });
  // composeVisualPrompt is shared with the episode-video batch path, so the
  // trigger words append here rather than threading a new param through it.
  const triggerClause = characterLoras
    .filter((l) => l.triggerWord)
    .map((l) => `${l.character?.name || 'character'} (${l.triggerWord})`)
    .join(', ');
  const prompt = triggerClause ? `${composedPrompt}\n\nFeaturing ${triggerClause}.` : composedPrompt;

  const jobId = await enqueueImageJob({
    prompt, world, settings, mode, series,
    options: { ...options, ...loraRenderOptions(characterLoras) },
    selectedModel,
    owner: `pipeline:${issueId}:${stageId}`,
    logLine: `🎬 Pipeline visual — issue=${issueId.slice(0, 8)} stage=${stageId}`,
  });
  return { jobId, mode, prompt };
}

// Validate the page/panel indices, lock, and non-empty description, then
// build the `pipeline-comic-panel-image-prompt` template variables. Shared by
// the 1:1 refine (replaces the description) and the N-candidate fan-out
// (non-destructive) so both feed the LLM identical context.
async function loadComicPanelPromptContext(issueId, pageIndex, panelIndex) {
  const pi = Number(pageIndex);
  const ni = Number(panelIndex);
  if (!Number.isInteger(pi) || pi < 0 || !Number.isInteger(ni) || ni < 0) {
    throw new ServerError('pageIndex and panelIndex must be non-negative integers', {
      status: 400, code: 'PIPELINE_PANEL_BAD_INDEX',
    });
  }
  const { issue, series } = await loadRefineContext(issueId);
  assertStageUnlocked(issue, 'comicPages');
  const pages = Array.isArray(issue.stages?.comicPages?.pages) ? [...issue.stages.comicPages.pages] : [];
  const page = pages[pi];
  if (!page) {
    throw new ServerError(`pageIndex ${pi} out of range (have ${pages.length})`, {
      status: 404, code: 'PIPELINE_COMIC_PAGE_NOT_FOUND',
    });
  }
  const panels = Array.isArray(page.panels) ? [...page.panels] : [];
  const panel = panels[ni];
  if (!panel) {
    throw new ServerError(`panelIndex ${ni} out of range (have ${panels.length})`, {
      status: 404, code: 'PIPELINE_COMIC_PANEL_NOT_FOUND',
    });
  }
  if (!(panel.description || '').trim()) {
    throw new ServerError('panel has no description to refine', {
      status: 400, code: 'PIPELINE_PANEL_EMPTY_DESCRIPTION',
    });
  }

  const prev = panels[ni - 1];
  const next = panels[ni + 1];
  // Drop dialogue rows whose line is empty/whitespace — matches the same
  // filter `composeComicPagePrompt` applies, so the refine template doesn't
  // get fed noisy `CHAR: ""` fragments that would confuse the LLM.
  const dialogue = Array.isArray(panel.dialogue) && panel.dialogue.length
    ? panel.dialogue
      .map((d) => {
        const character = (d.character || 'CHAR').trim() || 'CHAR';
        const line = (d.line || '').trim();
        return line ? `${character}: "${line}"` : null;
      })
      .filter(Boolean)
      .join(' / ')
    : '';

  const variables = {
    series: seriesBibleCtx(series),
    issue: issueCtx(issue),
    pageNumber: pi + 1,
    panelNumber: ni + 1,
    panelCount: panels.length,
    description: (panel.description || '').slice(0, 4000),
    caption: (panel.caption || '').slice(0, 1000),
    hasCaption: !!(panel.caption || '').trim(),
    dialogue,
    hasDialogue: !!dialogue,
    sfx: (panel.sfx || '').slice(0, 500),
    hasSfx: !!(panel.sfx || '').trim(),
    hasNeighbors: !!(prev || next),
    previousPanel: neighborText(prev),
    nextPanel: neighborText(next),
  };
  return { issue, pi, ni, pages, page, panels, panel, variables };
}

/**
 * Run the `pipeline-comic-panel-image-prompt` template against the current
 * panel + surrounding context, then persist the refined description on the
 * panel. Returns { panel, page, issue, stage, runId, changes, providerId }.
 */
export async function refineComicPanelPrompt(issueId, pageIndex, panelIndex, options = {}) {
  const { pi, ni, pages, page, panels, panel, variables } =
    await loadComicPanelPromptContext(issueId, pageIndex, panelIndex);

  const { refined, changes, runId, providerId } = await runPromptRefine({
    templateName: 'pipeline-comic-panel-image-prompt',
    variables,
    options,
    source: 'pipeline-comic-panel-prompt-refine',
    logTag: `Pipeline comic panel refine — issue=${issueId.slice(0, 8)} p=${pi + 1} panel=${ni + 1}`,
  });

  panels[ni] = { ...panel, description: refined };
  pages[pi] = { ...page, panels };
  const { issue: updatedIssue, stage } = await updateStage(issueId, 'comicPages', {
    status: 'edited',
    pages,
  });
  return { panel: panels[ni], page: pages[pi], issue: updatedIssue, stage, runId, changes, providerId };
}

/**
 * Generate N candidate image-gen prompts for a single comic panel WITHOUT
 * mutating the panel (issue #904). The user copies one or applies it to the
 * description via the existing refine/edit paths. Returns
 * { candidates, requested, pageIndex, panelIndex }.
 */
export async function generateComicPanelImagePrompts(issueId, pageIndex, panelIndex, { count, ...options } = {}) {
  const { pi, ni, variables } = await loadComicPanelPromptContext(issueId, pageIndex, panelIndex);
  const { candidates, requested } = await runImagePromptCandidates({
    count,
    templateName: 'pipeline-comic-panel-image-prompt',
    variables,
    options,
    source: 'pipeline-comic-panel-image-prompts',
    logTag: `Pipeline comic panel image-prompts — issue=${issueId.slice(0, 8)} p=${pi + 1} panel=${ni + 1}`,
  });
  return { candidates, requested, pageIndex: pi, panelIndex: ni };
}