Skip to content

Write HTML. Render video. Built for agents.

11.2 KB
Raw Blame
import {
  DEFAULT_FRAME_STATUS,
  FRAME_STATUSES,
  type FrameStatus,
  type StoryboardFrame,
  type StoryboardGlobals,
  type StoryboardManifest,
  type StoryboardWarning,
} from "./types.js";

/**
 * Lenient parser for `STORYBOARD.md`.
 *
 * The canonical (structured) format is:
 *
 * ```markdown
 * ---
 * format: 1920x1080
 * message: "Ship a launch video in an afternoon"
 * arc: Problem → Solution
 * audience: indie devs on X
 * ---
 *
 * ## Frame 3 — The feature in action
 * - duration: 6s
 * - transition_in: crossfade
 * - status: animated
 * - src: compositions/frames/03-feature.html
 *
 * The diff animates line by line as the narration says "...".
 * ```
 *
 * The parser is deliberately tolerant: it never throws, it accepts freeform
 * narrative, it recognizes `Frame` / `Beat` / `Scene` section headings at H2 or
 * H3, and it records anything surprising as a {@link StoryboardWarning} rather
 * than failing. Unknown frontmatter / metadata keys are preserved in `extra`.
 */
export function parseStoryboard(source: string): StoryboardManifest {
  const warnings: StoryboardWarning[] = [];
  const { globals, bodyStartLine, body } = parseFrontmatter(source, warnings);
  const frames = parseFrames(body, bodyStartLine, warnings);
  return { globals, frames, warnings };
}

// Headings that begin a frame section: `## Frame N`, `### Beat 1.1`, `## Scene 2`.
// Detection-only (ends at the keyword) — the title is sliced off in code. A single
// `[ \t]+` before the required keyword stays linear; avoids the polynomial backtracking
// a trailing `[\s…]*(.*)$` would add on tab-heavy input (CodeQL js/polynomial-redos).
export const FRAME_HEADING_RE = /^(#{2,3})[ \t]+(?:frame|beat|scene)\b/i;
/** Leading separators between the frame keyword and its title text. */
const FRAME_TITLE_SEP_RE = /^[\s.:—-]+/;
/** Any markdown heading; captures the `#` run so section depth can be compared. */
const HEADING_LEVEL_RE = /^(#{1,6})\s+/;
/** A metadata list item: `- key: value` or `* key: value`. */
const META_RE = /^\s*[-*]\s+([A-Za-z_][\w-]*)\s*:\s*(.+?)\s*$/;
/** Leading integer of a frame label, e.g. `3` in `3 — Title` or `1` in `1.1`. */
const LEADING_INT_RE = /^(\d+)/;
/** First numeric token in a duration string, e.g. `6` in `6s`, `6.5` in `6.5 sec`. */
const DURATION_NUM_RE = /(\d+(?:\.\d+)?)/;
/** Metadata keys that all map to the transition-in field. */
const TRANSITION_KEYS = new Set(["transition_in", "transitionin", "transition"]);
/** Metadata keys that all map to the one-line scene description. */
const SCENE_KEYS = new Set(["scene", "description", "summary", "caption"]);
/**
 * Aliases that all map to the voiceover/narration line. The single source of
 * truth — `editStoryboard.ts` imports this so the read and write sides can't
 * drift (one would silently fail to match the other's field name).
 */
export const VOICEOVER_ALIASES = ["voiceover", "vo", "voice_over", "narration"] as const;
const VOICEOVER_KEYS = new Set<string>(VOICEOVER_ALIASES);

interface FrontmatterResult {
  globals: StoryboardGlobals;
  /** 1-based line number where the body (post-frontmatter) begins. */
  bodyStartLine: number;
  body: string;
}

function emptyGlobals(): StoryboardGlobals {
  return { extra: {} };
}

function isFrameStatus(value: string): value is FrameStatus {
  return (FRAME_STATUSES as readonly string[]).includes(value);
}

// ── Frontmatter ───────────────────────────────────────────────────────────────

/** Locate the `---`-delimited frontmatter block, or null when there is none. */
function findFrontmatterRange(
  lines: string[],
  warnings: StoryboardWarning[],
): { start: number; end: number } | null {
  let start = 0;
  while (start < lines.length && (lines[start] ?? "").trim() === "") start++;
  if ((lines[start] ?? "").trim() !== "---") return null;

  for (let i = start + 1; i < lines.length; i++) {
    if ((lines[i] ?? "").trim() === "---") return { start, end: i };
  }
  warnings.push({
    message: "Frontmatter opening '---' has no closing '---'; treating whole file as body.",
    line: start + 1,
  });
  return null;
}

function parseFrontmatterEntries(
  lines: string[],
  start: number,
  end: number,
  warnings: StoryboardWarning[],
): StoryboardGlobals {
  const globals = emptyGlobals();
  for (let i = start + 1; i < end; i++) {
    const raw = lines[i] ?? "";
    if (raw.trim() === "") continue;
    const colon = raw.indexOf(":");
    if (colon === -1) {
      warnings.push({
        message: `Ignored non key:value frontmatter line: "${raw.trim()}"`,
        line: i + 1,
      });
      continue;
    }
    const key = raw.slice(0, colon).trim().toLowerCase();
    assignGlobal(globals, key, stripQuotes(raw.slice(colon + 1).trim()));
  }
  return globals;
}

function parseFrontmatter(source: string, warnings: StoryboardWarning[]): FrontmatterResult {
  const lines = source.split(/\r?\n/);
  const range = findFrontmatterRange(lines, warnings);
  if (!range) return { globals: emptyGlobals(), bodyStartLine: 1, body: source };

  const globals = parseFrontmatterEntries(lines, range.start, range.end, warnings);
  const body = lines.slice(range.end + 1).join("\n");
  return { globals, bodyStartLine: range.end + 2, body };
}

function assignGlobal(globals: StoryboardGlobals, key: string, value: string): void {
  switch (key) {
    case "format":
      globals.format = value;
      break;
    case "message":
      globals.message = value;
      break;
    case "arc":
      globals.arc = value;
      break;
    case "audience":
      globals.audience = value;
      break;
    default:
      globals.extra[key] = value;
  }
}

// ── Frames ────────────────────────────────────────────────────────────────────

interface FrameSection {
  headingText: string;
  headingLine: number;
  /** Heading depth (number of leading `#`) that opened this frame section. */
  level: number;
  lines: string[];
}

/** Open a new frame section if `line` is a frame heading, else null. */
function openFrameSection(line: string, headingLine: number): FrameSection | null {
  const match = FRAME_HEADING_RE.exec(line);
  if (!match) return null;
  const headingText = line.slice(match[0].length).replace(FRAME_TITLE_SEP_RE, "").trim();
  return { headingText, headingLine, level: (match[1] ?? "##").length, lines: [] };
}

/**
 * Whether `line` ends the current frame: a non-frame heading at the same or
 * shallower depth (e.g. a sibling `## Fonts`). Deeper sub-headings (e.g.
 * `#### Beats`) stay part of the frame's narrative.
 */
function endsFrameSection(line: string, current: FrameSection | null): boolean {
  if (!current) return false;
  const heading = HEADING_LEVEL_RE.exec(line);
  return heading !== null && (heading[1] ?? "").length <= current.level;
}

function parseFrames(
  body: string,
  bodyStartLine: number,
  warnings: StoryboardWarning[],
): StoryboardFrame[] {
  const lines = body.split(/\r?\n/);
  const sections: FrameSection[] = [];
  let current: FrameSection | null = null;

  for (let i = 0; i < lines.length; i++) {
    const line = lines[i] ?? "";
    const opened = openFrameSection(line, bodyStartLine + i);
    if (opened) {
      sections.push(opened);
      current = opened;
    } else if (endsFrameSection(line, current)) {
      current = null;
    } else if (current) {
      current.lines.push(line);
    }
  }

  return sections.map((section, idx) => buildFrame(section, idx + 1, warnings));
}

function buildFrame(
  section: FrameSection,
  index: number,
  warnings: StoryboardWarning[],
): StoryboardFrame {
  const frame: StoryboardFrame = { index, status: DEFAULT_FRAME_STATUS, narrative: "", extra: {} };

  const { number, title } = parseHeading(section.headingText);
  if (number !== undefined) frame.number = number;
  if (title) frame.title = title;

  const narrativeLines: string[] = [];
  for (const line of section.lines) {
    const meta = META_RE.exec(line);
    if (meta) {
      applyMeta(
        frame,
        (meta[1] ?? "").toLowerCase(),
        (meta[2] ?? "").trim(),
        section.headingLine,
        warnings,
      );
    } else {
      narrativeLines.push(line);
    }
  }
  frame.narrative = narrativeLines.join("\n").trim();
  return frame;
}

function parseHeading(text: string): { number?: number; title?: string } {
  if (!text) return {};
  const intMatch = LEADING_INT_RE.exec(text);
  if (!intMatch) return { title: text };

  const number = Number.parseInt(intMatch[1] ?? "", 10);
  const rest = text
    .slice((intMatch[0] ?? "").length)
    .replace(/^[\s.:—-]+/, "")
    .trim();
  return { number, title: rest || undefined };
}

/** Setter for a recognized metadata key. Extra trailing args are ignored by simple setters. */
type MetaSetter = (
  frame: StoryboardFrame,
  value: string,
  headingLine: number,
  warnings: StoryboardWarning[],
) => void;

/** Map of metadata key (and aliases) → setter. Keeps {@link applyMeta} a flat dispatch. */
const META_SETTERS = new Map<string, MetaSetter>([
  ["duration", applyDuration],
  ["status", applyStatus],
  ["poster", applyPoster],
  [
    "src",
    (frame, value) => {
      frame.src = value;
    },
  ],
  ...keyedSetters(TRANSITION_KEYS, (frame, value) => {
    frame.transitionIn = value;
  }),
  ...keyedSetters(SCENE_KEYS, (frame, value) => {
    frame.scene = value;
  }),
  ...keyedSetters(VOICEOVER_KEYS, (frame, value) => {
    frame.voiceover = stripQuotes(value);
  }),
]);

function keyedSetters(keys: Set<string>, setter: MetaSetter): Array<[string, MetaSetter]> {
  return [...keys].map((key) => [key, setter]);
}

function applyMeta(
  frame: StoryboardFrame,
  key: string,
  value: string,
  headingLine: number,
  warnings: StoryboardWarning[],
): void {
  const setter = META_SETTERS.get(key);
  if (setter) setter(frame, value, headingLine, warnings);
  else frame.extra[key] = value;
}

function applyPoster(frame: StoryboardFrame, value: string): void {
  const num = DURATION_NUM_RE.exec(value);
  if (num) frame.poster = Number.parseFloat(num[1] ?? "");
}

function applyDuration(
  frame: StoryboardFrame,
  value: string,
  headingLine: number,
  warnings: StoryboardWarning[],
): void {
  frame.duration = value;
  const num = DURATION_NUM_RE.exec(value);
  if (num) {
    frame.durationSeconds = Number.parseFloat(num[1] ?? "");
    return;
  }
  warnings.push({
    message: `Frame ${frame.index}: could not parse duration "${value}".`,
    line: headingLine,
    frameIndex: frame.index,
  });
}

function applyStatus(
  frame: StoryboardFrame,
  value: string,
  headingLine: number,
  warnings: StoryboardWarning[],
): void {
  const normalized = value.toLowerCase();
  if (isFrameStatus(normalized)) {
    frame.status = normalized;
    return;
  }
  frame.extra.status = value;
  warnings.push({
    message: `Frame ${frame.index}: unknown status "${value}"; defaulting to "${DEFAULT_FRAME_STATUS}".`,
    line: headingLine,
    frameIndex: frame.index,
  });
}

function stripQuotes(value: string): string {
  if (value.length >= 2) {
    const first = value[0];
    const last = value[value.length - 1];
    if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
      return value.slice(1, -1);
    }
  }
  return value;
}