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

13.1 KB
Raw Blame
/**
 * Universe Builder — prompt compilation.
 *
 * Pure render-prompt assembly: joins the universe's influence token lists +
 * style context and compiles the template into an ordered list of image-gen
 * prompts (variations / composite sheets / canon entries). No storage or
 * peer-sync. Split out of the former monolithic `universeBuilder.js` (#2529);
 * the barrel at `../universeBuilder.js` re-exports this module so existing
 * import paths keep working.
 */

import { composeStyledPrompt } from '../../lib/composeStyledPrompt.js';
import { joinInfluenceList } from '../../lib/universeVisualStyle.js';
import { promptAddition } from '../../lib/modelInput.js';
import { flattenCanonDescriptorFragments, richCanonDescriptorFragments } from '../../lib/canonPrompt.js';
import { getWorldCategoryKeys, normalizeCategoryKey, ENTRY_REF_KIND } from './sanitize.js';

// Re-exported so this module's existing importers (universeCanon.js,
// pipeline/seriesTitleLogo.js, seriesVoiceDiscover.js, seriesGenerate.js) are
// unchanged — the canonical definition now lives in universeVisualStyle.js,
// shared with the browser (#8442).
export { joinInfluenceList };

// Collapse newlines + control chars in user-supplied free text before
// embedding in a prompt. Defense-in-depth against a logline / styleNotes /
// variation label containing "\n# Output contract\n…" that could redirect the
// LLM's output structure. `trimTo` (the universe sanitizer) only trims
// leading/trailing whitespace, so embedded newlines flow through untouched
// without this pass.
export const stripPromptControlChars = (s) =>
  typeof s === 'string' ? s.replace(/[\r\n\t\f\v\u0085\u2028\u2029]+/g, ' ').trim() : '';

const identityText = (s) => s;

/**
 * Render the "established universe context" prompt section shared by the
 * Universe Builder LLM actions (auto-sort, promote-variation,
 * generate-category-variations). Returns the full block including leading
 * `\n# <header>\n` and trailing newline, ready to interpolate; returns `''`
 * when no fields populate so callers can drop the block entirely.
 *
 * Accepts a sanitized universe object or a shaped `{ logline, premise,
 * styleNotes }` literal (the expand-variations path passes the literal).
 *
 * @param {object|null|undefined} universe — sanitized universe or a shaped
 *   `{ logline, premise, styleNotes }` literal; `null`/`undefined` returns ''.
 * @param {object} [options]
 * @param {boolean} [options.includePremise=false] — emit a `PREMISE:` line.
 * @param {boolean} [options.includeEmbrace=true] — emit an
 *   `EMBRACE INFLUENCES:` line from `universe.influences.embrace`. Off for
 *   callers that render their own influences section.
 * @param {boolean} [options.escape=false] — collapse newlines/control chars
 *   in user-supplied text. Auto-sort opts in; promote/expand stayed off
 *   historically and we preserve that to avoid behavior drift.
 * @param {string} [options.headerSuffix=''] — appended after `Universe
 *   context — ` to bias the LLM.
 */
export function buildUniverseStyleContext(universe, options = {}) {
  if (!universe) return '';
  const {
    includePremise = false,
    includeEmbrace = true,
    escape = false,
    headerSuffix = '',
  } = options;
  const safeText = escape ? stripPromptControlChars : identityText;
  const lines = [];
  if (universe.logline) lines.push(`LOGLINE: ${safeText(universe.logline)}`);
  if (includePremise && universe.premise) lines.push(`PREMISE: ${safeText(universe.premise)}`);
  if (universe.styleNotes) lines.push(`STYLE NOTES: ${safeText(universe.styleNotes)}`);
  if (includeEmbrace) {
    const embraceTokens = joinInfluenceList(universe.influences?.embrace);
    if (embraceTokens) lines.push(`EMBRACE INFLUENCES: ${safeText(embraceTokens)}`);
  }
  if (lines.length === 0) return '';
  const header = headerSuffix ? `Universe context — ${headerSuffix}` : 'Universe context';
  return `\n# ${header}\n${lines.join('\n\n')}\n`;
}

// Order matches the Universe Builder tab order (Cast → Places → Objects) so
// the compiled-prompts list is stable across renders.
const CANON_TRUNKS = Object.freeze([
  { key: 'characters', category: 'canon:characters' },
  { key: 'places',     category: 'canon:places' },
  { key: 'objects',    category: 'canon:objects' },
]);

// Synthesize a render prompt from a canon entry. `entry.prompt` wins when
// hand-authored; otherwise stitch the kind's descriptive fields. Output is
// fed through `composeStyledPrompt(...)` so the universe's embrace tokens
// still prefix every canon render.
export function synthesizeCanonPrompt(kind, entry) {
  if (!entry) return '';
  if (typeof entry.prompt === 'string' && entry.prompt.trim()) return entry.prompt.trim();
  // Identifier seed: `name` is the shared anchor for all kinds. For
  // `places`, the bible sanitizer allows entries whose ONLY identifier is
  // a slugline (e.g. "EXT. FOUNDRY CITY — DAY") with no separate name — fall
  // back to slugline so those entries don't synthesize to an empty seed and
  // get silently skipped at render time.
  const name = typeof entry.name === 'string' ? entry.name.trim() : '';
  const sluglineId = (kind === 'places' && typeof entry.slugline === 'string')
    ? entry.slugline.trim()
    : '';
  const identifier = name || sluglineId;
  const body = flattenCanonDescriptorFragments(richCanonDescriptorFragments(kind, entry));
  if (identifier && body) return `${identifier} — ${body}`;
  return identifier || body;
}

/**
 * Compile the universe template into an ordered list of full image-gen
 * prompts. Each entry combines the universe's style prompt with one
 * variation from a chosen category, one composite sheet, or one canon entry.
 *
 *   promptMode: 'variations' | 'sheets' | 'canon' | 'all'
 *
 *   selection: { landscapes: 'all' | string[], characters: ... }
 *     - 'all' → use every variation
 *     - array of labels → only those labels (case-insensitive match)
 *     - missing key → skip the category entirely
 *
 *   canonSelection: { characters?: 'all' | string[], places?: ..., objects?: ... }
 *     - 'all' → render every entry in that canon trunk
 *     - array of names → only those names (case-insensitive match against
 *       `name` and, for places, `slugline`)
 *     - missing key → skip the trunk entirely
 *
 *   batchPerVariation: how many renders per variation (1..20)
 */
export function compilePrompts(universe, options = {}) {
  if (!universe) return [];
  const promptMode = ['variations', 'sheets', 'canon', 'all'].includes(options.promptMode)
    ? options.promptMode
    : 'variations';
  const selection = options.selection && typeof options.selection === 'object'
    ? options.selection
    : Object.fromEntries(getWorldCategoryKeys(universe.categories).map((c) => [c, 'all']));
  const normalizedSelection = {};
  for (const [key, value] of Object.entries(selection)) {
    const normalized = normalizeCategoryKey(key);
    if (normalized) normalizedSelection[normalized] = value;
  }
  const batchPerVariation = Math.max(1, Math.min(20, Number(options.batchPerVariation) || 1));

  // The universe's stored influences are the baseline; per-batch overrides
  // append on top so the user can layer an extra-style chip, a style preset,
  // or an extra negative without editing the persistent influences. Token
  // lists are comma-joined to match composeStyledPrompt's input expectation.
  const baselineEmbrace = joinInfluenceList(universe.influences?.embrace);
  const baselineAvoid = joinInfluenceList(universe.influences?.avoid);
  const embraceParts = [baselineEmbrace, options.stylePresetPrompt, options.extraStyle]
    .map((s) => (typeof s === 'string' ? s.trim() : ''))
    .filter(Boolean);
  const avoidParts = [baselineAvoid, options.stylePresetNegative, options.extraNegative]
    .map((s) => (typeof s === 'string' ? s.trim() : ''))
    .filter(Boolean);
  const stylePreset = {
    prompt: embraceParts.join(', '),
    negativePrompt: avoidParts.join(', '),
  };
  // Each block folded around an entry's own prompt, listed so the render's
  // sent-prompt record shows what PortOS added (#11317). The batch's own
  // negative is the user's text, so it is not an addition.
  const promptAdditions = [
    promptAddition('universe-style', 'Universe style', baselineEmbrace),
    promptAddition('style-preset', options.stylePresetLabel ? `Style preset: ${options.stylePresetLabel}` : 'Style preset', options.stylePresetPrompt),
    promptAddition('extra-style', 'Batch extra style', options.extraStyle),
    promptAddition('universe-avoid', 'Universe avoid (negative prompt)', baselineAvoid),
    promptAddition('style-preset-negatives', 'Style preset negatives', options.stylePresetNegative),
  ].filter(Boolean);
  const compiled = [];

  if (promptMode === 'variations' || promptMode === 'all') {
    for (const category of getWorldCategoryKeys(normalizedSelection)) {
      const sel = normalizedSelection[category];
      if (!sel) continue;
      const variations = universe.categories?.[category]?.variations || [];
      const filtered = sel === 'all'
        ? variations
        : variations.filter((v) => Array.isArray(sel) && sel.some((s) => s.toLowerCase() === v.label.toLowerCase()));
      for (const variation of filtered) {
        const { prompt, negativePrompt } = composeStyledPrompt(variation.prompt, '', stylePreset);
        for (let i = 0; i < batchPerVariation; i += 1) {
          compiled.push({
            category,
            label: variation.label,
            prompt,
            negativePrompt,
            promptAdditions,
            batchIndex: i,
            // `entryRef` lets the collection hook stamp the rendered filename
            // back onto this exact variation regardless of subsequent label
            // edits or bucket moves. Older universes can be missing `id` until
            // the next write through sanitizeTemplate — fall through silently
            // when that happens; the variation just won't accrue a render
            // history until it next gets persisted.
            ...(variation.id ? { entryRef: { kind: ENTRY_REF_KIND.VARIATION, categoryKey: category, id: variation.id } } : {}),
          });
        }
      }
    }
  }

  if (promptMode === 'sheets' || promptMode === 'all') {
    const sheetSelection = options.sheetSelection || 'all';
    const sheets = universe.compositeSheets || [];
    const filteredSheets = sheetSelection === 'all'
      ? sheets
      : sheets.filter((s) => Array.isArray(sheetSelection) && sheetSelection.some((label) => label.toLowerCase() === s.label.toLowerCase()));
    for (const sheet of filteredSheets) {
      const { prompt, negativePrompt } = composeStyledPrompt(sheet.prompt, '', stylePreset);
      const category = sheet.kind === 'world_pitch_poster'
        ? 'world_pitch_posters'
        : 'composite_sheets';
      for (let i = 0; i < batchPerVariation; i += 1) {
        compiled.push({
          category,
          label: sheet.label,
          prompt,
          negativePrompt,
          promptAdditions,
          batchIndex: i,
          ...(sheet.id ? { entryRef: { kind: ENTRY_REF_KIND.SHEET, id: sheet.id } } : {}),
        });
      }
    }
  }

  if (promptMode === 'canon' || promptMode === 'all') {
    const canonSelection = options.canonSelection && typeof options.canonSelection === 'object'
      ? options.canonSelection
      : null;
    if (canonSelection) {
      for (const trunk of CANON_TRUNKS) {
        const sel = canonSelection[trunk.key];
        if (!sel) continue;
        const entries = Array.isArray(universe[trunk.key]) ? universe[trunk.key] : [];
        const filtered = sel === 'all'
          ? entries
          : entries.filter((e) => Array.isArray(sel) && sel.some((s) => {
              const needle = s.toLowerCase();
              if (typeof e.name === 'string' && e.name.toLowerCase() === needle) return true;
              // Slugline is places-only (see canonSelection docstring above
              // and BIBLE_FIELD_WHITELIST). Avoid matching a stray slugline
              // field on a character/object payload — that field isn't part of
              // the canon contract for those kinds.
              if (trunk.key === 'places'
                  && typeof e.slugline === 'string'
                  && e.slugline.toLowerCase() === needle) return true;
              return false;
            }));
        for (const entry of filtered) {
          const seed = synthesizeCanonPrompt(trunk.key, entry);
          // An entry with no name and no descriptive content yields nothing —
          // skip rather than enqueue a style-prompt-only render that would
          // produce a generic image with no identity anchor.
          if (!seed) continue;
          const { prompt, negativePrompt } = composeStyledPrompt(seed, '', stylePreset);
          for (let i = 0; i < batchPerVariation; i += 1) {
            compiled.push({
              category: trunk.category,
              label: entry.name || entry.slugline || trunk.key,
              prompt,
              negativePrompt,
              promptAdditions,
              batchIndex: i,
              ...(entry.id ? { entryRef: { kind: ENTRY_REF_KIND.CANON, kindKey: trunk.key, id: entry.id } } : {}),
            });
          }
        }
      }
    }
  }

  return compiled;
}