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

12.9 KB
Raw Blame
/**
 * Scene-list extraction — split a prose draft OR a TV teleplay into a
 * structured `scenes[]` shape both Writers Room and Pipeline can consume.
 *
 * Mirrors the bibleExtractor.js pattern: this module owns the LLM call +
 * sanitization, the caller owns persistence. Returns the same scene shape
 * the writers-room evaluator's `script` analysis produces, so a writers-room
 * scene array and a pipeline-extracted scene array are byte-for-byte the
 * same shape (the Pipeline UI then reads `description` ← `visualPrompt`
 * for legacy field-name compat — see `extractedScenesToStoryboards` below).
 *
 * Two source modes:
 *
 *   - `prose`   → uses the existing `writers-room-script` stage prompt
 *                 (prose-paragraph granularity, sluglines invented).
 *   - `teleplay`→ uses the new `pipeline-extract-scenes` stage prompt
 *                 (sluglines already present in the teleplay markdown,
 *                  parse them rather than invent).
 */

import { runStagedLLM } from './stageRunner.js';
import { BIBLE_KIND, pickPromptFields } from '../lib/storyBible.js';
import { normalizeShotType, normalizeScreenDirection } from '../lib/shotGrammar.js';
import { isStr, trimTo } from '../lib/textUtils.js';

export const SOURCE_KIND = Object.freeze({ PROSE: 'prose', TELEPLAY: 'teleplay' });

const STAGE_FOR_SOURCE = Object.freeze({
  [SOURCE_KIND.PROSE]: 'writers-room-script',
  [SOURCE_KIND.TELEPLAY]: 'pipeline-extract-scenes',
});

// Per-field caps. Match the BIBLE_LIMITS pattern: bound every LLM-sourced
// string so a runaway scene list can't push stages.storyboards past
// STAGE_OUTPUT_MAX (400kB) on the issue-persist round-trip.
const SCENE_LIMITS = Object.freeze({
  ID_MAX: 80,
  HEADING_MAX: 200,
  SLUGLINE_MAX: 200,
  SUMMARY_MAX: 2000,
  CHARACTER_NAME_MAX: 100,
  CHARACTERS_PER_SCENE_MAX: 24,
  ACTION_MAX: 2000,
  DIALOGUE_LINE_MAX: 1000,
  DIALOGUE_ENTRIES_MAX: 60,
  VISUAL_PROMPT_MAX: 4000,
  SOURCE_SEG_ID_MAX: 80,
  SOURCE_SEG_IDS_MAX: 32,
  // Shots are bounded by the prompt's 3–8 guidance, but cap higher here so
  // a creative LLM doesn't lose work in the slice — the UI/CD path can
  // collapse extras into clip groups (see episodeVideo clip grouping).
  SHOTS_PER_SCENE_MAX: 16,
  SHOT_DESCRIPTION_MAX: 2000,
  // Bound durations to the same envelope the prompt asks for (2–10 s) with
  // a defensive ceiling so a runaway value doesn't extend a render queue.
  SHOT_DURATION_MIN: 1,
  SHOT_DURATION_MAX: 30,
});

// ---------- canonical scene shape (single source of truth) ----------

// Sanitize one LLM-emitted shot into the same shape the UI persists. The UI's
// add-shot path generates ids client-side; LLM output may supply its own.
// `continuityFromShotId` is best-effort — a stray reference to an unknown
// shot id is dropped at the scene level (after all ids are known).
function sanitizeShot(sh, i) {
  if (!sh || typeof sh !== 'object') return null;
  const id = trimTo(sh.id, SCENE_LIMITS.ID_MAX) || `shot-${String(i + 1).padStart(2, '0')}`;
  const description = trimTo(sh.description, SCENE_LIMITS.SHOT_DESCRIPTION_MAX);
  if (!description) return null;
  const rawDuration = Number(sh.durationSeconds);
  const durationSeconds = Number.isFinite(rawDuration)
    ? Math.max(SCENE_LIMITS.SHOT_DURATION_MIN, Math.min(SCENE_LIMITS.SHOT_DURATION_MAX, Math.round(rawDuration)))
    : 4;
  // Continuity is only meaningful when chained; null means "fresh framing".
  const continuityRaw = trimTo(sh.continuityFromShotId, SCENE_LIMITS.ID_MAX);
  return {
    id,
    description,
    durationSeconds,
    continuityFromShotId: continuityRaw || null,
    // Film-grammar signals (#1315) — both null when the extractor/UI didn't
    // tag them, so the continuity check skips an unclassified shot rather than
    // guessing. Normalized against their controlled vocabularies above.
    shotType: normalizeShotType(sh.shotType),
    screenDirection: normalizeScreenDirection(sh.screenDirection),
  };
}

function sanitizeShots(rawList) {
  if (!Array.isArray(rawList)) return [];
  const cleaned = rawList
    .slice(0, SCENE_LIMITS.SHOTS_PER_SCENE_MAX)
    .map(sanitizeShot)
    .filter(Boolean);
  // A shot can only chain from an EARLIER shot in the same scene — forward
  // refs, self-refs, and refs to dropped/unknown ids all collapse to null
  // (findIndex returns -1 for any id not in `cleaned`).
  return cleaned.map((shot, idx) => {
    if (!shot.continuityFromShotId) return shot;
    const targetIdx = cleaned.findIndex((s) => s.id === shot.continuityFromShotId);
    if (targetIdx < 0 || targetIdx >= idx) {
      return { ...shot, continuityFromShotId: null };
    }
    return shot;
  });
}

function sanitizeScene(s, i) {
  if (!s || typeof s !== 'object') return null;
  const id = trimTo(s.id, SCENE_LIMITS.ID_MAX) || `scene-${String(i + 1).padStart(2, '0')}`;
  const heading = trimTo(s.heading, SCENE_LIMITS.HEADING_MAX) || `Scene ${i + 1}`;
  const slugline = trimTo(s.slugline, SCENE_LIMITS.SLUGLINE_MAX);
  return {
    id,
    heading,
    slugline: slugline || null,
    summary: trimTo(s.summary, SCENE_LIMITS.SUMMARY_MAX),
    characters: Array.isArray(s.characters)
      ? s.characters.map((c) => trimTo(c, SCENE_LIMITS.CHARACTER_NAME_MAX)).filter(Boolean).slice(0, SCENE_LIMITS.CHARACTERS_PER_SCENE_MAX)
      : [],
    action: trimTo(s.action, SCENE_LIMITS.ACTION_MAX),
    dialogue: Array.isArray(s.dialogue)
      ? s.dialogue
          .filter((d) => d && typeof d === 'object' && (isStr(d.character) || isStr(d.line)))
          .slice(0, SCENE_LIMITS.DIALOGUE_ENTRIES_MAX)
          .map((d) => ({
            character: trimTo(d.character, SCENE_LIMITS.CHARACTER_NAME_MAX),
            line: trimTo(d.line, SCENE_LIMITS.DIALOGUE_LINE_MAX),
          }))
      : [],
    visualPrompt: trimTo(s.visualPrompt, SCENE_LIMITS.VISUAL_PROMPT_MAX),
    shots: sanitizeShots(s.shots),
    sourceSegmentIds: Array.isArray(s.sourceSegmentIds)
      ? s.sourceSegmentIds.map((segId) => trimTo(segId, SCENE_LIMITS.SOURCE_SEG_ID_MAX)).filter(Boolean).slice(0, SCENE_LIMITS.SOURCE_SEG_IDS_MAX)
      : [],
  };
}

/**
 * Sanitize the full LLM envelope: `{ title, logline, scenes: [...] }`.
 * Cap at 200 scenes to match the visual-stage `scenes` cap in
 * `pipeline/issues.js#sanitizeVisualStage` so an over-eager extraction
 * can't silently lose entries to a downstream slice.
 */
export function sanitizeSceneList(raw, { maxScenes = 200 } = {}) {
  const obj = raw && typeof raw === 'object' ? raw : {};
  const list = Array.isArray(obj.scenes) ? obj.scenes : [];
  return {
    title: isStr(obj.title) ? obj.title.trim() : null,
    logline: isStr(obj.logline) ? obj.logline.trim() : null,
    scenes: list.slice(0, maxScenes).map(sanitizeScene).filter(Boolean),
  };
}

// ---------- canonical scene list (beat sheet, no LLM) ----------

// Match the beat sheet's `## Scenes` heading (any heading level, case-insensitive).
const SCENES_HEADING_RE = /^#{1,6}\s+Scenes\b/i;
// A heading line of any level — used to bound the `## Scenes` section.
const ANY_HEADING_RE = /^#{1,6}\s+/;
// A scene list entry must start with a markdown list marker (`-`/`*`/`+`,
// `1.`/`1)`) or an explicit `Scene N` — so an intro sentence inside the
// `## Scenes` section isn't mistaken for a scene.
const SCENE_ENTRY_RE = /^\s*(?:[-*+]\s|\d{1,3}[.)]\s|Scene\s+\d)/i;
// Strip a leading markdown list marker.
const LIST_MARKER_RE = /^\s*(?:[-*+]|\d{1,3}[.)])\s*/;
// Strip a leading `Scene N` token (with an optional —/–/:/-/. separator),
// capturing the scene number.
const SCENE_PREFIX_RE = /^Scene\s+(\d{1,3})\b\s*[—–:.\-]?\s*(.*)$/i;

/**
 * Parse the beat sheet's canonical `## Scenes` list (#1552) into a lightweight
 * `[{ number, slugline, summary }]`. The beat-sheet prompt emits a numbered
 * markdown list of `Scene N — INT./EXT. LOCATION — TIME: <beats clause>`; this
 * is the single source of truth for scene boundaries every adaptation inherits.
 *
 * Returns `[]` when there's no `## Scenes` section or it holds no parseable
 * entries — the caller falls back to the LLM slugline-parse path.
 */
export function parseBeatSheetScenes(markdown) {
  if (!isStr(markdown)) return [];
  const lines = markdown.split(/\r\n|\r|\n/);
  const start = lines.findIndex((l) => SCENES_HEADING_RE.test(l.trim()));
  if (start < 0) return [];

  const out = [];
  for (let j = start + 1; j < lines.length; j++) {
    const line = lines[j];
    if (ANY_HEADING_RE.test(line.trim())) break; // next section ends the list
    if (!SCENE_ENTRY_RE.test(line)) continue; // skip blanks / intro prose
    let entry = line.replace(LIST_MARKER_RE, '').trim();
    if (!entry) continue;
    let number = null;
    const sm = entry.match(SCENE_PREFIX_RE);
    if (sm) {
      number = Number(sm[1]);
      entry = sm[2].trim();
    }
    if (!entry) continue;
    // A colon separates the slugline from the beats clause. Match the first
    // colon NOT followed by a digit, so a clock TIME in the slugline
    // (`INT. OFFICE — 3:00 PM: the meeting`) splits on the `PM:` separator
    // rather than the `3:00` time — preserving the full slugline for matching.
    let slugline = entry;
    let summary = '';
    const colon = entry.search(/:(?!\d)/);
    if (colon >= 0) {
      slugline = entry.slice(0, colon).trim();
      summary = entry.slice(colon + 1).trim();
    }
    if (!slugline) continue;
    out.push({ number: Number.isFinite(number) ? number : out.length + 1, slugline, summary });
  }
  return out;
}

/**
 * Map the beat sheet's canonical `## Scenes` list directly to the sanitized
 * scene shape — no LLM call. Used to seed storyboards so `storyboards.scenes`
 * numbers/sluglines match the comic pages' (both inherit the same canonical
 * list). Returns `[]` when the beat sheet has no parseable scene list.
 */
export function scenesFromBeatSheet(markdown, { maxScenes = 200 } = {}) {
  const parsed = parseBeatSheetScenes(markdown);
  if (!parsed.length) return [];
  const raw = {
    scenes: parsed.map((p) => ({
      id: `scene-${String(p.number).padStart(2, '0')}`,
      heading: p.slugline ? `Scene ${p.number} — ${p.slugline}` : `Scene ${p.number}`,
      slugline: p.slugline,
      summary: p.summary,
    })),
  };
  return sanitizeSceneList(raw, { maxScenes }).scenes;
}

// ---------- LLM driver ----------

/**
 * @param {object} args
 * @param {string} args.source          prose body OR teleplay markdown
 * @param {string} args.sourceKind      'prose' | 'teleplay'
 * @param {Array}  [args.characters]    bible entries (for deference)
 * @param {Array}  [args.places]        bible entries (for deference)
 * @param {Array}  [args.objects]       bible entries (for deference)
 * @param {object} [args.work]          variables consumed by writers-room-script (`work.title`, `work.kind`, `work.wordCount`)
 * @param {object} [args.series]        variables consumed by pipeline-extract-scenes (`series.name`, `series.styleNotes`)
 * @param {object} [args.issue]         variables consumed by pipeline-extract-scenes (`issue.number`, `issue.title`)
 * @param {string} [args.providerOverride]
 * @param {string} [args.tag]           override the run-tracking source tag
 * @returns {Promise<{ extracted: { title, logline, scenes }, runId, providerId, model }>}
 */
export async function extractScenes({
  source,
  sourceKind = SOURCE_KIND.PROSE,
  characters = [],
  places = [],
  objects = [],
  work,
  series,
  issue,
  providerOverride,
  modelOverride,
  tag,
}) {
  const stage = STAGE_FOR_SOURCE[sourceKind];
  if (!stage) throw new Error(`extractScenes: unknown sourceKind "${sourceKind}"`);
  if (!isStr(source) || !source.trim()) {
    throw new Error('extractScenes: source is required');
  }

  // Both prompts read the same `existing<X>Json` envelope so the model can
  // defer to canonical character/place names instead of re-improvising.
  // Pipeline's series.characters and Writers Room's per-work characters both
  // sanitize through `pickPromptFields` to strip ids/timestamps/source/notes.
  const variables = {
    returnsJson: true,
    sourceKind,
    existingCharactersJson: JSON.stringify((characters || []).map((c) => pickPromptFields(BIBLE_KIND.CHARACTER, c))),
    existingPlacesJson: JSON.stringify((places || []).map((p) => pickPromptFields(BIBLE_KIND.PLACE, p))),
    existingObjectsJson: JSON.stringify((objects || []).map((o) => pickPromptFields(BIBLE_KIND.OBJECT, o))),
  };
  // Variable-shape compat: writers-room-script.md reads `{{draftBody}}` +
  // `{{work.*}}`; pipeline-extract-scenes.md reads `{{teleplay}}` +
  // `{{series.*}}` / `{{issue.*}}`. Populate both — Mustache silently drops
  // unbound names.
  variables.draftBody = source;
  variables.teleplay = source;
  if (work) variables.work = work;
  if (series) variables.series = series;
  if (issue) variables.issue = issue;

  const result = await runStagedLLM(stage, variables, {
    providerOverride,
    modelOverride,
    returnsJson: true,
    source: tag || `scene-extract-${sourceKind}`,
  });

  return {
    extracted: sanitizeSceneList(result.content),
    runId: result.runId,
    providerId: result.providerId,
    model: result.model,
  };
}