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

52.1 KB
Raw Blame
/**
 * Pipeline issue routes — Issue/Episode CRUD plus stage operations: text-LLM
 * generation/restore, scene/page/canon extraction, per-page and per-panel
 * renders, prompt refinement, scene/episode video, and the auto-run text
 * chain.
 */

import { Router } from 'express';
import { z } from 'zod';
import { asyncHandler, ServerError } from '../../lib/errorHandler.js';
import {
  validateRequest,
  imageEdgeSchema,
  refineImagePixelCap,
  PIXEL_CAP_MESSAGE,
  storyboardSceneSchema,
} from '../../lib/validation.js';
import * as seriesSvc from '../../services/pipeline/series.js';
import * as issuesSvc from '../../services/pipeline/issues.js';
import { generateStage } from '../../services/pipeline/textStages.js';
import * as textStageProgress from '../../services/pipeline/textStageProgress.js';
import * as autoRunner from '../../services/pipeline/autoRunner.js';
import {
  enqueueVisualImage,
  renderComicPage,
  enqueueStoryboardSceneVideo,
  enqueueStoryboardShotStartFrame,
  refineComicPanelPrompt,
  refineComicPageRender,
  refineStoryboardScenePrompt,
  generateComicPanelImagePrompts,
  generateStoryboardSceneImagePrompts,
} from '../../services/pipeline/visualStages.js';
import { IMAGE_PROMPT_CANDIDATE_MAX } from '../../services/pipeline/refineHelpers.js';
import {
  extractCanonFromProse, summarizeCanonExtraction,
  describeCanonFromProse, summarizeDescribeGaps,
} from '../../services/universeCanon.js';
import { getSeriesCanon } from '../../services/pipeline/seriesCanon.js';
import { startEpisodeVideoForIssue } from '../../services/pipeline/episodeVideo.js';
import { COMIC_PAGE_VARIANTS } from '../../services/pipeline/owners.js';
import { ASPECT_RATIOS, QUALITIES } from '../../lib/creativeDirectorPresets.js';
import { QUEUEABLE_IMAGE_MODES } from '../../services/imageGen/modes.js';
import { extractScenes, scenesFromBeatSheet, SOURCE_KIND } from '../../services/sceneExtractor.js';
import { resolveSeriesLlmOverride } from '../../lib/seriesLlmOverride.js';
import { parseComicScript } from '../../lib/comicScriptParser.js';
import {
  LENGTH_PROFILE_NAMES,
  CUSTOM_PAGE_MIN, CUSTOM_PAGE_MAX, CUSTOM_MINUTE_MIN, CUSTOM_MINUTE_MAX,
} from '../../lib/issueLength.js';
import { ARC_ROLES } from '../../lib/storyArc.js';
import { mapServiceError, countExtractedCanon } from './shared.js';

import textStageRecoveryRouter from './textStageRecovery.js';

const router = Router();

// ---- Issue schemas ----

const stageInputSchema = z.object({
  status: z.enum(issuesSvc.STAGE_STATUSES).optional(),
  input: z.string().max(issuesSvc.STAGE_INPUT_MAX).optional(),
  output: z.string().max(issuesSvc.STAGE_OUTPUT_MAX).optional(),
  errorMessage: z.string().max(issuesSvc.STAGE_NOTES_MAX).optional(),
  locked: z.boolean().optional(),
});

// Strict base arm for the stage-record union below — a bare text-stage patch
// (only base fields) validates here, but a payload carrying any visual/audio
// extra key fails this arm and is routed to the matching specific arm instead
// of being silently key-stripped. The non-strict `stageInputSchema` stays the
// `.extend()` base for the specific arms (they re-apply `.strict()` themselves).
const baseStageStrictSchema = stageInputSchema.strict();

// Light per-cue arm for the audio stage (issue #863). The service-side
// `sanitizeAudioCue` enforces the real shape (ids, time sentinels, gain clamp);
// here we only bound sizes so a corrupt payload can't balloon the request.
const audioCueInputSchema = z.object({
  id: z.string().trim().max(issuesSvc.AUDIO_CUE_ID_MAX).optional(),
  label: z.string().max(issuesSvc.AUDIO_CUE_LABEL_MAX).nullable().optional(),
  prompt: z.string().max(issuesSvc.AUDIO_CUE_PROMPT_MAX).nullable().optional(),
  engine: z.string().trim().max(issuesSvc.AUDIO_CUE_ENGINE_MAX).nullable().optional(),
  startSec: z.number().nullable().optional(),
  endSec: z.number().nullable().optional(),
  trackFilename: z.string().trim().max(issuesSvc.AUDIO_FILENAME_MAX).nullable().optional(),
  durationSec: z.number().nullable().optional(),
  gain: z.number().nullable().optional(),
}).strip();

// Visual stage records also accept pages/scenes/cdProjectId/videoPath — those
// are arbitrary structured artifacts written by the visual UI. Keep the
// validation light here so the artifact shape can evolve without a schema
// migration; the service-level sanitizer caps array length.
const visualStageInputSchema = stageInputSchema.extend({
  pages: z.array(z.any()).max(200).optional(),
  // Scenes stay passthrough (the rich scene shape evolves freely), but each
  // scene's shots[] is validated through storyboardSceneSchema so a bad
  // shotType/screenDirection enum is rejected at the route (#1315) instead of
  // persisting unnormalized. Non-storyboard visual stages simply carry no shots.
  scenes: z.array(storyboardSceneSchema).max(200).optional(),
  cdProjectId: z.string().trim().max(64).nullable().optional(),
  videoPath: z.string().trim().max(1000).nullable().optional(),
  aspectRatio: z.enum(ASPECT_RATIOS).nullable().optional(),
  quality: z.enum(QUALITIES).nullable().optional(),
  // Per-stage gen config — image mode + optional pinned model + optional
  // refine-LLM override. Sanitizer drops the field entirely when nothing
  // is set, so a `null` here clears it.
  genConfig: z.object({
    imageMode: z.enum(['auto', ...QUEUEABLE_IMAGE_MODES]).optional(),
    imageModelId: z.string().trim().max(200).nullable().optional(),
    refineProvider: z.string().trim().max(200).nullable().optional(),
    refineModel: z.string().trim().max(200).nullable().optional(),
    applyCharacterLoras: z.boolean().optional(),
  }).nullable().optional(),
  // Comic-issue front cover. Only meaningful on the comicPages stage; the
  // service-side sanitizer drops the field on other visual stages.
  cover: z.object({
    script: z.string().max(8000).optional(),
    imageJobId: z.string().trim().max(200).nullable().optional(),
    prompt: z.string().max(16_000).nullable().optional(),
  }).nullable().optional(),
  // Comic-issue back cover — identical shape to `cover`. Only meaningful
  // on the comicPages stage. The render route + filename hook treat the
  // two slots symmetrically; only the rendered prompt differs (no
  // masthead, explicit no-text negative — back covers are illustration-
  // only).
  backCover: z.object({
    script: z.string().max(8000).optional(),
    imageJobId: z.string().trim().max(200).nullable().optional(),
    prompt: z.string().max(16_000).nullable().optional(),
  }).nullable().optional(),
}).strict();

// Audio stage payloads carry lines[] (voice-over per dialogue line), a nullable
// music descriptor, the whole-episode `audioMode` selector, and arc-driven
// `cues[]` (issue #863). Light validation — the sanitizer in
// services/pipeline/issues.js enforces per-line / per-music / per-cue shape.
// Without this arm in the union below, audio PATCHes fall through and the
// base/visual arms strip lines/music/audioMode/cues.
//
// `.strict()` is load-bearing here: the union arms below all share the same
// optional base fields, so a plain object parses against *any* arm and Zod's
// default key-stripping would let an audio payload match the visual arm FIRST,
// silently dropping audioMode/cues. Strict arms reject unknown keys, so an
// audio payload (with audioMode/cues/lines/music) only validates against THIS
// arm and reaches the audio sanitizer intact.
const audioStageInputSchema = stageInputSchema.extend({
  lines: z.array(z.any()).max(1000).optional(),
  music: z.any().nullable().optional(),
  audioMode: z.enum(issuesSvc.AUDIO_MODES).optional(),
  cues: z.array(audioCueInputSchema).max(issuesSvc.AUDIO_CUES_MAX).optional(),
}).strict();

const issuePatchSchema = z.object({
  title: z.string().trim().min(1).max(issuesSvc.TITLE_MAX).optional(),
  number: z.number().int().min(1).max(9999).optional(),
  status: z.enum(issuesSvc.ISSUE_STATUSES).optional(),
  // Phase 2 of Story Arc Planning: optional pointer back to a season +
  // ordinal within that season. `null` clears the assignment.
  seasonId: z.string().trim().min(1).max(issuesSvc.SEASON_ID_MAX).nullable().optional(),
  arcPosition: z.number().int().min(0).max(issuesSvc.ARC_POSITION_MAX).nullable().optional(),
  arcRole: z.enum(ARC_ROLES).nullable().optional(),
  // Per-issue length profile. Drives the prompt-template size targets
  // (beats / prose words / page count / minute count). pageTarget +
  // minutesTarget are only meaningful when lengthProfile === 'custom'.
  lengthProfile: z.enum(LENGTH_PROFILE_NAMES).optional(),
  pageTarget: z.number().int().min(CUSTOM_PAGE_MIN).max(CUSTOM_PAGE_MAX).nullable().optional(),
  minutesTarget: z.number().int().min(CUSTOM_MINUTE_MIN).max(CUSTOM_MINUTE_MAX).nullable().optional(),
  // Stage-record arms are all `.strict()` (see audioStageInputSchema above):
  // every arm shares the same optional base fields, so a non-strict arm would
  // accept (and key-strip) a payload meant for a sibling arm. With strict arms
  // a payload only validates against the arm whose extra keys it actually
  // carries — visual payloads (pages/scenes/…) reach the visual arm, audio
  // payloads (lines/music/audioMode/cues) reach the audio arm, and bare
  // text-stage patches (status/output/locked only) fall through to the base.
  // Order is now defensive rather than load-bearing, but we still place the
  // more-specific arms first; the bare base last.
  stages: z.record(z.string(), z.union([visualStageInputSchema, audioStageInputSchema, baseStageStrictSchema])).optional(),
  ephemeral: z.boolean().optional(),
}).refine((p) => Object.keys(p).length > 0, { message: 'patch must include at least one field' });

const generateSchema = z.object({
  seedInput: z.string().max(issuesSvc.STAGE_INPUT_MAX).optional(),
  providerId: z.string().trim().max(80).optional(),
  model: z.string().trim().max(200).optional(),
  // Explicit source stages to feed the generation (backport support: generate
  // any stage FROM any other populated stage). Omit for the conventional
  // forward source. The service drops the target itself and empty stages.
  sourceStageIds: z.array(z.enum(issuesSvc.TEXT_STAGE_IDS)).optional(),
});

// Path params for the text-stage progress stream. The stage must be a text
// stage — a visual/audio stage has no text-generation channel to attach to.
const stageProgressParamsSchema = z.object({
  id: z.string().trim().min(1).max(200),
  stageId: z.enum(issuesSvc.TEXT_STAGE_IDS),
});

const visualGenerateSchema = z.object({
  description: z.string().trim().min(1).max(8000),
  // Matched against the series places bible when present.
  slugline: z.string().trim().max(200).optional(),
  negativePrompt: z.string().trim().max(2000).optional(),
  extraStyle: z.string().trim().max(2000).optional(),
  mode: z.enum(QUEUEABLE_IMAGE_MODES).optional(),
  modelId: z.string().trim().max(64).optional(),
  width: imageEdgeSchema,
  height: imageEdgeSchema,
  steps: z.number().int().min(1).max(150).optional(),
  cfgScale: z.number().min(0).max(30).optional(),
  guidance: z.number().min(0).max(30).optional(),
  seed: z.number().int().min(0).optional(),
  // Per-scene wardrobe picks threaded from the storyboards UI — the generic
  // visual route has no scene index, so the client sends the selected
  // appearances directly. Each pins one canon character to one of its
  // wardrobes; the prompt builder appends the wardrobe after the character's
  // physical description.
  characterAppearances: z.array(z.object({
    characterId: z.string().trim().min(1).max(120),
    wardrobeId: z.string().trim().min(1).max(120).nullable().optional(),
  })).max(50).optional(),
  // Per-render opt-out for trained character-LoRA auto-apply (local mode).
  applyCharacterLoras: z.boolean().optional().default(true),
}).refine(refineImagePixelCap, { message: PIXEL_CAP_MESSAGE, path: ['width'] });

// Full-comic-page render: same knobs as panel render minus `description` /
// `slugline` (the prompt is built server-side from the page's panels[] so it
// stays in sync with whatever the script-extractor produced).
const comicPageRenderSchema = z.object({
  negativePrompt: z.string().trim().max(2000).optional(),
  extraStyle: z.string().trim().max(2000).optional(),
  mode: z.enum(QUEUEABLE_IMAGE_MODES).optional(),
  modelId: z.string().trim().max(64).optional(),
  width: imageEdgeSchema,
  height: imageEdgeSchema,
  steps: z.number().int().min(1).max(150).optional(),
  cfgScale: z.number().min(0).max(30).optional(),
  guidance: z.number().min(0).max(30).optional(),
  seed: z.number().int().min(0).optional(),
  // See covers.js's makeCoverRenderSchema for the proof/final semantics.
  target: z.enum(COMIC_PAGE_VARIANTS).optional().default('proof'),
  useProofAsBase: z.boolean().optional().default(false),
  // Consistency reference: re-render this page using an adjacent ('prior'/'next')
  // or explicit (0-based index) already-rendered page as a reference image, so a
  // continuing scene keeps incidental/un-described characters + environment
  // consistent. Resolved + bounds-checked in enqueueVisualComicPage.
  //   - omitted / 'auto' → auto-chain off the prior page within the same scene,
  //     render fresh across a scene boundary (the default).
  //   - 'none' → force a fresh render with no reference, even mid-scene.
  //   - 'prior' / 'next' / <index> → explicit reference (errors if unrendered).
  referencePage: z.union([z.enum(['prior', 'next', 'auto', 'none']), z.number().int().min(0)]).optional(),
  // Per-render opt-out for trained character-LoRA auto-apply (local mode).
  applyCharacterLoras: z.boolean().optional().default(true),
}).refine(refineImagePixelCap, { message: PIXEL_CAP_MESSAGE, path: ['width'] });

// Per-page "Refine" — a small image-to-image correction to an already-rendered
// page (issue #1534). `instruction` is the user's free-text change; the LLM
// adjusts the page's stored render prompt and the page re-renders i2i from its
// own existing image. The render-tuning fields mirror comicPageRenderSchema,
// minus the compose-from-source-only `useProofAsBase` / `referencePage` /
// `applyCharacterLoras` (a from-self refine has no proof-vs-final base choice
// and no fresh character matching). `target` selects which rendered variant to
// refine; absent → server auto-picks (final when present, else proof).
const comicPageRefineSchema = z.object({
  instruction: z.string().trim().min(1).max(2000),
  providerId: z.string().trim().max(80).optional(),
  model: z.string().trim().max(200).optional(),
  target: z.enum(COMIC_PAGE_VARIANTS).optional(),
  // i2i denoise — low preserves the page, just enough to apply the change.
  initImageStrength: z.number().min(0).max(1).optional(),
  negativePrompt: z.string().trim().max(2000).optional(),
  // No `extraStyle`: the refine renders the LLM-adjusted prompt verbatim and
  // skips composeComicPagePrompt, so a style suffix would be silently dropped.
  mode: z.enum(QUEUEABLE_IMAGE_MODES).optional(),
  modelId: z.string().trim().max(64).optional(),
  width: imageEdgeSchema,
  height: imageEdgeSchema,
  steps: z.number().int().min(1).max(150).optional(),
  cfgScale: z.number().min(0).max(30).optional(),
  guidance: z.number().min(0).max(30).optional(),
  seed: z.number().int().min(0).optional(),
}).refine(refineImagePixelCap, { message: PIXEL_CAP_MESSAGE, path: ['width'] });

const episodeVideoSchema = z.object({
  aspectRatio: z.enum(ASPECT_RATIOS).optional(),
  quality: z.enum(QUALITIES).optional(),
  modelId: z.string().trim().max(64).optional(),
  force: z.boolean().optional(),
});

// Single-scene video render. Lighter schema than episodeVideo because there
// is no stitch step — just one t2v render against the scene's existing
// description.
const sceneVideoSchema = z.object({
  aspectRatio: z.enum(ASPECT_RATIOS).optional(),
  modelId: z.string().trim().max(64).optional(),
  negativePrompt: z.string().trim().max(2000).optional(),
  extraStyle: z.string().trim().max(2000).optional(),
});

// Provider/model picker for the LLM-driven panel/scene prompt refine. Both
// are optional — server falls back to the active provider + stage default.
const promptRefineSchema = z.object({
  providerId: z.string().trim().max(80).optional(),
  model: z.string().trim().max(200).optional(),
});

// Same picker plus a `count` for the non-destructive N-candidate fan-out
// (issue #904). `count` is clamped server-side to IMAGE_PROMPT_CANDIDATE_MAX,
// but bound it here too so an out-of-range value is a clean 400 rather than a
// silently-clamped surprise.
const imagePromptsSchema = promptRefineSchema.extend({
  count: z.number().int().min(1).max(IMAGE_PROMPT_CANDIDATE_MAX).optional().default(3),
});

// Source for scene extraction: which text stage to read from (`prose` →
// granular paragraph-grain breakdown via `writers-room-script`; `teleplay`
// → slugline-grain parse via `pipeline-extract-scenes`). `force` overrides
// the "you have N hand-curated scenes already" guard.
// Enum values match `SOURCE_KIND` verbatim so the route forwards `body.from`
// straight through — same string also names the issue's text stage.
const extractScenesSchema = z.object({
  from: z.enum([SOURCE_KIND.PROSE, SOURCE_KIND.TELEPLAY]).optional().default(SOURCE_KIND.TELEPLAY),
  providerOverride: z.string().trim().max(80).optional(),
  modelOverride: z.string().trim().max(128).optional(),
  force: z.boolean().optional(),
});

const extractComicPagesSchema = z.object({
  force: z.boolean().optional(),
});

const extractCanonFromScriptSchema = z.object({
  providerOverride: z.string().trim().max(80).optional(),
  model: z.string().trim().max(128).optional(),
});

const describeCanonFromProseSchema = z.object({
  providerOverride: z.string().trim().max(80).optional(),
  model: z.string().trim().max(128).optional(),
  // Nouns to backfill — typically the appears-in-this-issue entries that lack
  // a description. The server re-validates each against the universe canon.
  targets: z.array(z.object({
    id: z.string().trim().min(1).max(80),
    kind: z.enum(['character', 'place', 'object']),
  })).min(1).max(500),
});

// Stages whose `output` can be mined for canon. `prose` is the conventional
// source (auto-extracted post-generation); `comicScript`/`teleplay` let the
// writer pull characters introduced only in panel directions / dialogue cues.
const CANON_EXTRACT_STAGES = Object.freeze(['prose', 'comicScript', 'teleplay']);

// Per-issue truncation budget for canon extraction. Decoupled from the
// importer's source ceiling (which ingests a *whole book* — millions of
// chars): a pipeline issue's stage output is already hard-bounded at
// `STAGE_OUTPUT_MAX` (400KB), so this path operates at a fundamentally
// smaller scale. 200K clamps a long single-issue script before forwarding
// to the same `extractBible` machinery the importer uses, keeping the
// per-call corpus comfortably inside provider context windows.
const EXTRACT_CANON_CORPUS_MAX = 200_000;

const comicPagePatchSchema = z.object({
  rawText: z.string().max(40000),
});

const autoRunSchema = z.object({
  providerId: z.string().trim().max(80).optional(),
  model: z.string().trim().max(200).optional(),
  force: z.boolean().optional(),
  // Optional opt-in to extend the auto-run past text stages: kicks off the
  // episodeVideo handoff to Creative Director once scripts are done. Burns
  // GPU minutes, so default is off.
  includeVideo: z.boolean().optional(),
  aspectRatio: z.enum(ASPECT_RATIOS).optional(),
  quality: z.enum(QUALITIES).optional(),
  modelId: z.string().trim().max(64).optional(),
});

// =====================
// Issue routes
// =====================

// Server-owned issue vocabulary keeps client pickers aligned with persisted
// validation and importer/Creative Director contracts.
router.get('/config', (_req, res) => {
  res.json({ arcRoles: [...ARC_ROLES] });
});

// Recent issues across all series — used by the sidebar's dynamic Pipeline
// child list. Routes through `listRecentIssues` which sorts the FULL issue
// set by `updatedAt` desc before applying limit; `listIssues` would
// silently miss the most-recent items once the dataset grows past
// `ISSUES_PER_RESPONSE_MAX` (1000).
router.get('/issues/recent', asyncHandler(async (req, res) => {
  // Forward the raw query value to the service — it owns clamping +
  // non-finite handling, and applying our own `Number(...) || 10` here
  // would silently disagree with the service (e.g. limit=0 ends up as 10
  // via the route but clamps to 1 in the service). Pass through and let
  // listRecentIssues coerce.
  const [issues, series] = await Promise.all([
    // Fetch only the fields this endpoint returns, with the limit in SQL.
    issuesSvc.listRecentIssues({ limit: req.query.limit, withHistory: false, summary: true }),
    seriesSvc.listSeries(),
  ]);
  const seriesById = new Map(series.map((s) => [s.id, s.name]));
  res.json(issues.map((i) => ({
    id: i.id,
    title: i.title,
    number: i.number,
    seriesId: i.seriesId,
    seriesName: seriesById.get(i.seriesId) || '(unknown series)',
    updatedAt: i.updatedAt,
  })));
}));

router.get('/issues/:id', asyncHandler(async (req, res) => {
  const issue = await issuesSvc.getIssue(req.params.id).catch((err) => { throw mapServiceError(err); });
  res.json(issue);
}));

router.patch('/issues/:id', asyncHandler(async (req, res) => {
  const body = validateRequest(issuePatchSchema, req.body ?? {});
  const issue = await issuesSvc.updateIssue(req.params.id, body).catch((err) => { throw mapServiceError(err); });
  res.json(issue);
}));

router.delete('/issues/:id', asyncHandler(async (req, res) => {
  const r = await issuesSvc.deleteIssue(req.params.id).catch((err) => { throw mapServiceError(err); });
  res.json(r);
}));

// =====================
// Stage operations
// =====================

router.use(textStageRecoveryRouter);

router.post('/issues/:id/stages/:stageId/generate', asyncHandler(async (req, res) => {
  const { id, stageId } = req.params;
  if (!issuesSvc.TEXT_STAGE_IDS.includes(stageId)) {
    throw new ServerError(
      `Stage "${stageId}" is not generatable via text-LLM. Use the /visual endpoint for image stages.`,
      { status: 400, code: 'PIPELINE_NON_TEXT_STAGE' },
    );
  }
  const body = validateRequest(generateSchema, req.body ?? {});
  const result = await generateStage(id, stageId, body).catch((err) => { throw mapServiceError(err); });
  res.json(result);
}));

// Live progress for the POST above (#3393). Subscribe-then-trigger: attaching
// OPENS the channel, so the client can connect before (or concurrently with)
// the generate POST without racing it — and generation runs unchanged when
// nobody is listening. See services/pipeline/textStageProgress.js.
router.get('/issues/:id/stages/:stageId/generate/progress', (req, res) => {
  const { id, stageId } = validateRequest(stageProgressParamsSchema, req.params);
  textStageProgress.attachClient(id, stageId, res);
});

// Restore a prior text-stage version from history. See
// issuesSvc.restoreStageFromHistory for the reversibility semantics.
const restoreSchema = z.object({
  runId: z.string().trim().min(1).max(200),
});
router.post('/issues/:id/stages/:stageId/restore', asyncHandler(async (req, res) => {
  const { id, stageId } = req.params;
  if (!issuesSvc.TEXT_STAGE_IDS.includes(stageId)) {
    throw new ServerError(
      `Stage "${stageId}" does not support history restore`,
      { status: 400, code: 'PIPELINE_NON_TEXT_STAGE' },
    );
  }
  const body = validateRequest(restoreSchema, req.body ?? {});
  const issue = await issuesSvc.getIssue(id).catch((err) => { throw mapServiceError(err); });
  issuesSvc.assertStageUnlocked(issue, stageId);
  const result = await issuesSvc.restoreStageFromHistory(id, stageId, body.runId)
    .catch((err) => { throw mapServiceError(err); });
  res.json(result);
}));

// Auto-fill stages.storyboards.scenes[] from a text stage. Reads the issue's
// prose (paragraph-grain) or teleplay (slugline-grain) output, runs the
// shared scene extractor, and replaces stages.storyboards.scenes with the
// result mapped to the storyboards UI shape (visualPrompt → description).
router.post('/issues/:id/stages/storyboards/extract-scenes', asyncHandler(async (req, res) => {
  const body = validateRequest(extractScenesSchema, req.body ?? {});
  const issue = await issuesSvc.getIssue(req.params.id).catch((err) => { throw mapServiceError(err); });
  issuesSvc.assertStageUnlocked(issue, 'storyboards');

  const existing = Array.isArray(issue.stages?.storyboards?.scenes) ? issue.stages.storyboards.scenes : [];
  if (existing.length > 0 && !body.force) {
    throw new ServerError(
      `Storyboards already has ${existing.length} scene${existing.length === 1 ? '' : 's'} — pass { force: true } to replace`,
      { status: 409, code: 'PIPELINE_STORYBOARDS_NOT_EMPTY' },
    );
  }

  // Adapt a canonical scene to the pipeline storyboards UI shape: alias
  // `visualPrompt → description` (the textarea binding) and reset the per-scene
  // image-gen job fields. Rich fields (heading/summary/dialogue/...) ride along.
  // Fall back to the scene `summary` when there's no visualPrompt so a scene
  // that only carries the beats clause (the canonical-only case below) still
  // seeds a non-empty description — the refine/image/video paths require one.
  const toStoryboardScene = (s) => ({ ...s, description: s.visualPrompt || s.summary || '', imageJobId: null, prompt: null });

  // The beat sheet's canonical `## Scenes` list (#1552) is the single source of
  // truth for scene numbers + sluglines across every adaptation, so when it
  // exists we use it to ALIGN the storyboards scenes — guaranteeing their
  // numbers/sluglines match the comic pages'. But the list is sparse (no
  // dialogue / visual prompts / shots), and downstream stages need that rich
  // data — audio voice-over is built from `storyboards.scenes[].dialogue`. So
  // we still run the LLM extraction over the source text to get the rich fields,
  // then OVERLAY the canonical numbering/sluglines onto it (hybrid). Only when
  // there's no source text to extract from do we fall back to the canonical list
  // alone (deterministic, no dialogue — but there's nothing to extract it from).
  const canonicalScenes = scenesFromBeatSheet(issue.stages?.idea?.output || '');
  const series = await seriesSvc.getSeries(issue.seriesId).catch((err) => { throw mapServiceError(err); });

  const sourceKind = body.from;
  const source = (issue.stages?.[sourceKind]?.output || '').trim();
  if (!source && canonicalScenes.length === 0) {
    throw new ServerError(
      `Cannot extract scenes — issue's ${sourceKind} stage is empty`,
      { status: 400, code: 'PIPELINE_NO_SOURCE_FOR_SCENE_EXTRACT' },
    );
  }

  let extractedScenes = [];
  let runId = null;
  let providerId = null;
  let model = null;
  if (source) {
    // Fall back to the series' configured LLM when the client doesn't pass an
    // explicit override — every Pipeline LLM action should honor the
    // provider/model picked in the issue header (which mirrors series.llm).
    // Canon lives on the linked universe (Phase B.4). Orphan series render
    // with empty canon — extractScenes can still produce scenes from the
    // source text alone, just without character/place/object grounding.
    const canon = await getSeriesCanon(series);
    // A model id is provider-specific, so only inherit the series model when the
    // effective provider is still the series provider — otherwise an override
    // provider would be paired with a foreign model id and fail (same guard as
    // the extract-canon route). When the override switches providers without
    // naming a model, leave it blank so the new provider's default resolves.
    const { provider, model: resolvedModel } = resolveSeriesLlmOverride(series, {
      overrideProvider: body.providerOverride,
      overrideModel: body.modelOverride,
    });
    const result = await extractScenes({
      source,
      sourceKind,
      characters: canon.characters,
      places: canon.places,
      objects: canon.objects,
      work: { title: issue.title, kind: 'tv-episode' },
      series: { name: series.name, styleNotes: series.styleNotes },
      issue: { number: issue.number, title: issue.title },
      providerOverride: provider,
      modelOverride: resolvedModel,
      tag: `pipeline-storyboards-extract-${sourceKind}`,
    });
    extractedScenes = result.extracted.scenes;
    runId = result.runId;
    providerId = result.providerId;
    model = result.model;
  }

  // Overlay the canonical numbering/sluglines/headings onto the extracted scenes
  // (matched by position) when a canonical list exists — the canonical list wins
  // on identity/ordering while the LLM scene contributes dialogue/visualPrompt/
  // shots/characters. Extracted scenes beyond the canonical count are dropped so
  // the storyboards scene count matches the canonical (and comic-page) scene
  // count; canonical scenes beyond the extracted count carry no dialogue (there
  // was no matching extracted scene), seeding their description from the summary.
  const usedCanonicalList = canonicalScenes.length > 0;
  const finalScenes = usedCanonicalList
    ? canonicalScenes.map((c, i) => {
        // Base on the canonical scene `c` (full sanitized shape with empty
        // dialogue/shots/characters), overlay the LLM scene's rich fields, then
        // re-assert canonical identity (id/heading/slugline) so the canonical
        // numbering always wins. When there's no matching extracted scene
        // (`ext` is {}), the result is just `c` — empty dialogue, summary-seeded
        // description.
        const ext = extractedScenes[i] || {};
        return { ...c, ...ext, id: c.id, heading: c.heading, slugline: c.slugline, summary: ext.summary || c.summary };
      })
    : extractedScenes;

  const storyboardScenes = finalScenes.map(toStoryboardScene);
  const { issue: updatedIssue, stage } = await issuesSvc.updateStage(issue.id, 'storyboards', {
    status: storyboardScenes.length ? 'ready' : 'empty',
    scenes: storyboardScenes,
    lastRunId: runId,
    errorMessage: '',
  });

  res.json({
    issue: updatedIssue,
    stage,
    runId,
    providerId,
    model,
    sceneCount: storyboardScenes.length,
    // 'beat-sheet' when the response is purely the canonical list (no source to
    // extract from); otherwise the LLM source stage the rich fields came from.
    sourceKind: source ? sourceKind : 'beat-sheet',
    usedCanonicalList,
  });
}));

router.post('/issues/:id/stages/comicPages/extract-pages', asyncHandler(async (req, res) => {
  const body = validateRequest(extractComicPagesSchema, req.body ?? {});
  const issue = await issuesSvc.getIssue(req.params.id).catch((err) => { throw mapServiceError(err); });
  issuesSvc.assertStageUnlocked(issue, 'comicPages');

  const source = (issue.stages?.comicScript?.output || '').trim();
  if (!source) {
    throw new ServerError(
      `Cannot extract pages — issue's comicScript stage is empty`,
      { status: 400, code: 'PIPELINE_NO_SOURCE_FOR_PAGE_EXTRACT' },
    );
  }

  const existing = Array.isArray(issue.stages?.comicPages?.pages) ? issue.stages.comicPages.pages : [];
  if (existing.length > 0 && !body.force) {
    throw new ServerError(
      `Comic pages already has ${existing.length} page${existing.length === 1 ? '' : 's'} — pass { force: true } to replace`,
      { status: 409, code: 'PIPELINE_COMIC_PAGES_NOT_EMPTY' },
    );
  }

  const { pages, coverConcept, backCoverConcept } = parseComicScript(source);

  // Preserve a user-edited cover / back-cover script if one is already set —
  // only seed from the parsed concept when the slot is currently blank.
  // Otherwise an extract re-run would clobber a hand-curated cover/back. When
  // we DO seed, also clear any prior imageJobId / prompt — they were
  // rendered against the old (likely placeholder / fallback) script, so
  // leaving them would show a rendered image that doesn't match the new
  // concept text.
  //
  // The decision is made inside updateStageWithLatest so it reads the
  // freshest persisted cover/back, not the stale snapshot from the
  // getIssue read above. A concurrent cover/render call that writes
  // imageJobId between the two awaits would otherwise be silently
  // overwritten.
  const { issue: updatedIssue, stage } = await issuesSvc.updateStageWithLatest(
    issue.id,
    'comicPages',
    (currentStage) => {
      const currentCoverScript = currentStage?.cover?.script || '';
      const nextCover = coverConcept && !currentCoverScript
        ? { script: coverConcept, imageJobId: null, prompt: null }
        : currentStage?.cover ?? null;
      const currentBackScript = currentStage?.backCover?.script || '';
      const nextBackCover = backCoverConcept && !currentBackScript
        ? { script: backCoverConcept, imageJobId: null, prompt: null }
        : currentStage?.backCover ?? null;
      return {
        status: pages.length ? 'ready' : 'empty',
        pages,
        cover: nextCover,
        backCover: nextBackCover,
        errorMessage: '',
      };
    },
  );

  const panelCount = pages.reduce((n, p) => n + (p.panels?.length || 0), 0);
  res.json({
    issue: updatedIssue,
    stage,
    pageCount: pages.length,
    panelCount,
  });
}));

// Auto-extract runs only after `prose` (textStages.js:233); this endpoint
// lets the writer pull canon from a script stage on demand so characters
// introduced only in panel directions or dialogue cues land in the bible.
// Same autoLock + sourceSeriesId stamping as prose extraction so script-
// derived entries survive later AI refines.
router.post('/issues/:id/stages/:stageId/extract-canon', asyncHandler(async (req, res) => {
  const { id, stageId } = req.params;
  if (!CANON_EXTRACT_STAGES.includes(stageId)) {
    throw new ServerError(
      `Stage "${stageId}" does not support canon extraction — supported: ${CANON_EXTRACT_STAGES.join(', ')}`,
      { status: 400, code: 'PIPELINE_CANON_EXTRACT_BAD_STAGE' },
    );
  }
  const body = validateRequest(extractCanonFromScriptSchema, req.body ?? {});
  const issue = await issuesSvc.getIssue(id).catch((err) => { throw mapServiceError(err); });
  const rawCorpus = (issue.stages?.[stageId]?.output || '').trim();
  if (!rawCorpus) {
    throw new ServerError(
      `Cannot extract canon — issue's ${stageId} stage is empty`,
      { status: 400, code: 'PIPELINE_CANON_EXTRACT_NO_CORPUS' },
    );
  }
  const truncated = rawCorpus.length > EXTRACT_CANON_CORPUS_MAX;
  const corpus = truncated ? rawCorpus.slice(0, EXTRACT_CANON_CORPUS_MAX) : rawCorpus;
  if (truncated) {
    console.warn(`⚠️ Pipeline canon extract — issue=${id.slice(0, 8)} stage=${stageId} corpus truncated ${rawCorpus.length}→${EXTRACT_CANON_CORPUS_MAX}`);
  }
  const series = await seriesSvc.getSeries(issue.seriesId).catch((err) => { throw mapServiceError(err); });
  if (!series.universeId) {
    throw new ServerError(
      `Cannot extract canon — series has no linked universe. Link a universe in the series settings first.`,
      { status: 400, code: 'PIPELINE_CANON_EXTRACT_NO_UNIVERSE' },
    );
  }
  // Fall back to the series' configured LLM when the client doesn't pass an
  // explicit override — matches every other Pipeline LLM action (e.g.
  // storyboards/extract-scenes) so a manual extract honors the provider/model
  // picked in the series header instead of the global default.
  // A model id is provider-specific. Only inherit the series model when the
  // EFFECTIVE provider is still the series provider — otherwise the retry
  // picker's whole point (switch provider, keep "Default model") would forward
  // e.g. `providerOverride: anthropic` paired with a Codex/OpenAI model id and
  // fail. When the user overrode to a different provider without naming a
  // model, leave it blank so the extractor resolves that provider's default.
  const { provider, model } = resolveSeriesLlmOverride(series, {
    overrideProvider: body.providerOverride,
    overrideModel: body.model,
  });

  // Stamp the outcome on the stage so the Nouns UI can persist a
  // failure/partial banner and the user can retry with a different
  // provider/model. A hard failure (every kind threw) still records `failed`
  // before re-throwing so the banner survives even when the request 5xxes.
  let result;
  try {
    result = await extractCanonFromProse(series.universeId, {
      corpus,
      providerOverride: provider,
      modelOverride: model,
      parallel: true,
      autoLock: true,
      sourceSeriesId: series.id,
    });
  } catch (err) {
    const marker = summarizeCanonExtraction({ error: err, provider, model });
    await issuesSvc.updateStage(id, stageId, { canonExtraction: marker })
      .catch((e) => console.warn(`⚠️ Failed to record canon-extraction status for issue ${id.slice(0, 8)}: ${e.message}`));
    throw mapServiceError(err);
  }

  const marker = summarizeCanonExtraction({ results: result.results, failures: result.failures, provider, model });
  const { issue: stampedIssue } = await issuesSvc.updateStage(id, stageId, { canonExtraction: marker })
    .catch((err) => { throw mapServiceError(err); });

  res.json({
    universe: result.universe,
    issue: stampedIssue,
    canonExtraction: marker,
    failures: result.failures,
    extracted: countExtractedCanon(result.results),
    sourceStage: stageId,
    truncated,
  });
}));

// Backfill descriptions for canon nouns that have none, using ONLY what this
// stage's prose establishes. Distinct from extract-canon: extraction invents +
// flags missing renderable axes (so it never leaves a blank), while this pass
// is strictly prose-grounded — a noun the prose never describes comes back in
// the `descGaps` marker so the Nouns UI can flag the manuscript as thin instead
// of fabricating a description that the prose can't support.
router.post('/issues/:id/stages/:stageId/describe-canon', asyncHandler(async (req, res) => {
  const { id, stageId } = req.params;
  if (!CANON_EXTRACT_STAGES.includes(stageId)) {
    throw new ServerError(
      `Stage "${stageId}" does not support canon description — supported: ${CANON_EXTRACT_STAGES.join(', ')}`,
      { status: 400, code: 'PIPELINE_CANON_DESCRIBE_BAD_STAGE' },
    );
  }
  const body = validateRequest(describeCanonFromProseSchema, req.body ?? {});
  const issue = await issuesSvc.getIssue(id).catch((err) => { throw mapServiceError(err); });
  const rawCorpus = (issue.stages?.[stageId]?.output || '').trim();
  if (!rawCorpus) {
    throw new ServerError(
      `Cannot describe canon — issue's ${stageId} stage is empty`,
      { status: 400, code: 'PIPELINE_CANON_DESCRIBE_NO_CORPUS' },
    );
  }
  const corpus = rawCorpus.length > EXTRACT_CANON_CORPUS_MAX
    ? rawCorpus.slice(0, EXTRACT_CANON_CORPUS_MAX)
    : rawCorpus;
  const series = await seriesSvc.getSeries(issue.seriesId).catch((err) => { throw mapServiceError(err); });
  if (!series.universeId) {
    throw new ServerError(
      `Cannot describe canon — series has no linked universe. Link a universe in the series settings first.`,
      { status: 400, code: 'PIPELINE_CANON_DESCRIBE_NO_UNIVERSE' },
    );
  }
  // Same provider/model resolution as extract-canon so a manual describe honors
  // the series-header LLM (or the per-attempt picker override).
  const { provider, model } = resolveSeriesLlmOverride(series, {
    overrideProvider: body.providerOverride,
    overrideModel: body.model,
  });

  const result = await describeCanonFromProse(series.universeId, {
    corpus,
    targets: body.targets,
    providerOverride: provider,
    modelOverride: model,
  }).catch((err) => { throw mapServiceError(err); });

  const marker = summarizeDescribeGaps({ report: result.report, provider, model });
  const { issue: stampedIssue } = await issuesSvc.updateStage(id, stageId, { descGaps: marker })
    .catch((err) => { throw mapServiceError(err); });

  res.json({
    universe: result.universe,
    issue: stampedIssue,
    descGaps: marker,
    report: result.report,
    sourceStage: stageId,
  });
}));

// Per-page rawText patch — re-parses panels from the edited markdown so a
// subsequent render still gets a structured prompt. Page's `imageJobId` is
// preserved so the user doesn't lose an in-flight render after a save.
//
// The splice + per-panel imageJobId preservation runs inside
// updateStageWithLatest's computeFn so it reads the freshest persisted pages
// array. A concurrent page-level render that lands between a pre-queue read
// and our write would otherwise be reverted — including the imageJobId it
// just queued.
router.patch('/issues/:id/stages/comicPages/pages/:pageIndex', asyncHandler(async (req, res) => {
  const pageIndex = Number(req.params.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 body = validateRequest(comicPagePatchSchema, req.body ?? {});
  const { pages: reparsed } = parseComicScript(body.rawText);
  const fresh = reparsed[0] || { panels: [], rawText: body.rawText };

  const { issue: updatedIssue, stage } = await issuesSvc.updateStageWithLatest(
    req.params.id,
    '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],
        rawText: fresh.rawText || body.rawText,
        // Re-derive the scene marker from the edited header so editing
        // `## Page N — Scene M: SLUGLINE` retags the page (and clears it when
        // the marker is removed). `?? null` normalizes the absent case.
        sceneNumber: fresh.sceneNumber ?? null,
        sceneHeading: fresh.sceneHeading ?? null,
        panels: fresh.panels.map((p, i) => ({
          ...p,
          // Preserve in-flight per-panel jobIds against the freshest panels.
          imageJobId: currentPages[pageIndex].panels?.[i]?.imageJobId ?? p.imageJobId ?? null,
        })),
      };
      return { status: 'edited', pages: nextPages };
    },
  ).catch((err) => { throw mapServiceError(err); });
  res.json({ issue: updatedIssue, stage, page: stage.pages[pageIndex] });
}));

// Render a full comic page (multi-panel layout in one image) — the
// recommended default for cloud-class image models (Codex, Google Imagen);
// local diffusion models can render this but tend to produce draft-quality
// pages, so the per-panel `/visual` endpoint remains the fallback.
//
// Persists the returned jobId on stages.comicPages.pages[pageIndex].imageJobId
// so the UI can show the page-level render alongside the per-panel renders.
router.post('/issues/:id/stages/comicPages/pages/:pageIndex/render', asyncHandler(async (req, res) => {
  const pageIndex = Number(req.params.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 body = validateRequest(comicPageRenderSchema, req.body ?? {});

  // Validate the page exists up front so we skip the enqueue work entirely
  // when the index is bad. The service also throws ServerError(404) for the
  // same case (defense in depth — any other caller still gets a clean 404),
  // but checking here avoids loading the bible context just to error out.
  const issue = await issuesSvc.getIssue(req.params.id).catch((err) => { throw mapServiceError(err); });
  const pages = Array.isArray(issue.stages?.comicPages?.pages) ? issue.stages.comicPages.pages : [];
  if (!pages[pageIndex]) {
    throw new ServerError(
      `pageIndex ${pageIndex} out of range — comicPages has ${pages.length} page${pages.length === 1 ? '' : 's'}`,
      { status: 404, code: 'PIPELINE_COMIC_PAGE_NOT_FOUND' },
    );
  }

  // renderComicPage enqueues AND persists the in-flight slot onto
  // pages[pageIndex].{proofImage|finalImage} through the serialized issue write
  // tail (#2241) — the same shared entry point the CDO orchestrator tool calls,
  // so an orchestrated page completes exactly like a user-driven one. The
  // persist runs inside updateStageWithLatest's computeFn so the slot lands on
  // the freshest persisted pages array (a concurrent page edit or sibling
  // render can't be reverted by a stale snapshot).
  const result = await renderComicPage(req.params.id, { pageIndex, ...body })
    .catch((err) => { throw mapServiceError(err); });
  res.json(result);
}));

// AI prompt-refine + image-to-image re-render for a small correction to an
// already-rendered comic page (issue #1534). The service adjusts the page's
// stored render prompt per the user's instruction and re-renders i2i from the
// page's existing image; the new jobId + adjusted prompt land on the matching
// variant slot — same persist path as /render, so a concurrent edit or sibling
// render can't be reverted by a stale snapshot.
router.post('/issues/:id/stages/comicPages/pages/:pageIndex/refine-render', asyncHandler(async (req, res) => {
  const pageIndex = Number(req.params.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 body = validateRequest(comicPageRefineSchema, req.body ?? {});

  // Validate the page exists up front so a bad index skips the bible load + LLM
  // refine entirely (mirrors the /render route's pre-flight). The service also
  // 404s before the LLM call — this just fails faster and more cheaply.
  const issue = await issuesSvc.getIssue(req.params.id).catch((err) => { throw mapServiceError(err); });
  const pages = Array.isArray(issue.stages?.comicPages?.pages) ? issue.stages.comicPages.pages : [];
  if (!pages[pageIndex]) {
    throw new ServerError(
      `pageIndex ${pageIndex} out of range — comicPages has ${pages.length} page${pages.length === 1 ? '' : 's'}`,
      { status: 404, code: 'PIPELINE_COMIC_PAGE_NOT_FOUND' },
    );
  }

  // refineComicPageRender adjusts the page's stored render prompt (LLM),
  // re-renders i2i from the page's existing image, AND persists the new slot on
  // the matching variant through the serialized issue write tail (#2241) — same
  // shared code path the CDO orchestrator tool uses. A concurrent edit or
  // sibling render can't be reverted by a stale snapshot.
  const result = await refineComicPageRender(req.params.id, { pageIndex, ...body })
    .catch((err) => { throw mapServiceError(err); });
  res.json(result);
}));

// AI-driven prompt refinement for a single comic panel. Uses
// pipeline-comic-panel-image-prompt stage to elaborate the panel's existing
// description into a richer image-gen prompt, then persists the result on
// the panel.
router.post('/issues/:id/stages/comicPages/pages/:pageIndex/panels/:panelIndex/refine-prompt',
  asyncHandler(async (req, res) => {
    const body = validateRequest(promptRefineSchema, req.body ?? {});
    const result = await refineComicPanelPrompt(
      req.params.id,
      Number(req.params.pageIndex),
      Number(req.params.panelIndex),
      body,
    ).catch((err) => { throw mapServiceError(err); });
    res.json(result);
  }),
);

// Non-destructive N-candidate variant: generate `count` alternative image-gen
// prompts for one comic panel without touching the panel description. The
// client lists them and lets the user copy or apply one (issue #904).
router.post('/issues/:id/stages/comicPages/pages/:pageIndex/panels/:panelIndex/image-prompts',
  asyncHandler(async (req, res) => {
    const body = validateRequest(imagePromptsSchema, req.body ?? {});
    const result = await generateComicPanelImagePrompts(
      req.params.id,
      Number(req.params.pageIndex),
      Number(req.params.panelIndex),
      body,
    ).catch((err) => { throw mapServiceError(err); });
    res.json(result);
  }),
);

// AI-driven prompt refinement for a single storyboard scene. Mirror of the
// comic-panel refine but uses pipeline-storyboard-image-prompt.
router.post('/issues/:id/stages/storyboards/scenes/:index/refine-prompt',
  asyncHandler(async (req, res) => {
    const body = validateRequest(promptRefineSchema, req.body ?? {});
    const result = await refineStoryboardScenePrompt(
      req.params.id,
      Number(req.params.index),
      body,
    ).catch((err) => { throw mapServiceError(err); });
    res.json(result);
  }),
);

// Non-destructive N-candidate variant for a storyboard scene (issue #904).
router.post('/issues/:id/stages/storyboards/scenes/:index/image-prompts',
  asyncHandler(async (req, res) => {
    const body = validateRequest(imagePromptsSchema, req.body ?? {});
    const result = await generateStoryboardSceneImagePrompts(
      req.params.id,
      Number(req.params.index),
      body,
    ).catch((err) => { throw mapServiceError(err); });
    res.json(result);
  }),
);

// Render the start-frame image for a single shot inside a storyboard scene.
// Shot-level granularity sits parallel to the existing scene-level image
// render: a scene either has shots[] (per-shot images) or doesn't (per-scene
// image). Caller persists the jobId on `scene.shots[shotIndex].startFrameJobId`;
// the storyboards filename hook later stamps `startFrameFilename` on
// completion.
router.post(
  '/issues/:id/stages/storyboards/scenes/:sceneIndex/shots/:shotIndex/render',
  asyncHandler(async (req, res) => {
    const sceneIndex = Number(req.params.sceneIndex);
    const shotIndex = Number(req.params.shotIndex);
    if (!Number.isInteger(sceneIndex) || sceneIndex < 0 || !Number.isInteger(shotIndex) || shotIndex < 0) {
      throw new ServerError('sceneIndex and shotIndex must be non-negative integers', {
        status: 400, code: 'PIPELINE_SHOT_BAD_INDEX',
      });
    }
    const body = validateRequest(comicPageRenderSchema, req.body ?? {});
    const result = await enqueueStoryboardShotStartFrame(req.params.id, sceneIndex, shotIndex, body)
      .catch((err) => { throw mapServiceError(err); });
    res.json(result);
  }),
);

// Render a single storyboard scene as a video clip, independent of the
// full episode-video stitch. Persists the resulting jobId on the scene's
// `sceneVideoJobId` so a reload still shows the in-flight render.
router.post('/issues/:id/stages/storyboards/scenes/:index/video', asyncHandler(async (req, res) => {
  const idx = Number(req.params.index);
  if (!Number.isInteger(idx) || idx < 0) {
    throw new ServerError('scene index must be a non-negative integer', {
      status: 400, code: 'PIPELINE_SCENE_BAD_INDEX',
    });
  }
  const body = validateRequest(sceneVideoSchema, req.body ?? {});
  const result = await enqueueStoryboardSceneVideo(req.params.id, idx, body)
    .catch((err) => { throw mapServiceError(err); });
  res.json(result);
}));

router.post('/issues/:id/stages/:stageId/visual', asyncHandler(async (req, res) => {
  const { id, stageId } = req.params;
  if (!issuesSvc.VISUAL_STAGE_IDS.includes(stageId)) {
    throw new ServerError(
      `Stage "${stageId}" is not a visual stage. Use /generate for text-LLM stages.`,
      { status: 400, code: 'PIPELINE_NON_VISUAL_STAGE' },
    );
  }
  if (stageId === 'episodeVideo') {
    const body = validateRequest(episodeVideoSchema, req.body ?? {});
    const result = await startEpisodeVideoForIssue(id, body).catch((err) => { throw mapServiceError(err); });
    res.json(result);
    return;
  }
  const body = validateRequest(visualGenerateSchema, req.body ?? {});
  const result = await enqueueVisualImage(id, stageId, body).catch((err) => { throw mapServiceError(err); });
  res.json(result);
}));

// =====================
// Auto-run text chain
// =====================

router.post('/issues/:id/auto-run-text', asyncHandler(async (req, res) => {
  const body = validateRequest(autoRunSchema, req.body ?? {});
  // Validate the issue exists before kicking off the runner so a bad id
  // returns 404 instead of a half-started run.
  await issuesSvc.getIssue(req.params.id).catch((err) => { throw mapServiceError(err); });
  const result = await autoRunner.startAutoRunTextStages(req.params.id, body);
  res.json({
    ...result,
    sseUrl: `/api/pipeline/issues/${req.params.id}/auto-run-text/progress`,
  });
}));

router.get('/issues/:id/auto-run-text/progress', (req, res) => {
  const attached = autoRunner.attachClient(req.params.id, res);
  if (!attached) {
    throw new ServerError('No active auto-run for this issue', { status: 404 });
  }
});

router.post('/issues/:id/auto-run-text/cancel', asyncHandler(async (req, res) => {
  const canceled = autoRunner.cancelAutoRun(req.params.id);
  res.json({ canceled });
}));

export default router;