Skip to content

Write HTML. Render video. Built for agents.

17.9 KB
Raw Blame
import {
  duplicateElementInHtml,
  patchElementInHtml,
  removeElementFromHtml,
  splitElementInHtml,
} from "@hyperframes/studio-server";
import type {
  AppliedFileMutation,
  PatchOperation,
  SourceMutationTarget,
} from "@hyperframes/studio-server";
import { fpsToNumber, parseFpsWithDefault } from "@hyperframes/core";
import { isInsideSpan, sameInstant, spansShareTime } from "@hyperframes/core/clip-facts";
import { readCompositionFps } from "../utils/compositionFps.js";
import { readFileSync } from "node:fs";
import type { ProjectTimeline, TimelineRow } from "./describeProject.js";
import { resolveRef } from "./resolveRef.js";
import { parseTimeExpression } from "./timeExpr.js";
import { setCommandExitCode } from "../utils/commandResult.js";
import { parseSetAssignments, type SetAssignment } from "./a2Mutations.js";

export type MutationVerb = "move" | "trim" | "split" | "delete" | "set" | "duplicate";

export const FIELDS_READ_BY_VERB: Record<MutationVerb, readonly string[]> = {
  move: ["time", "overwrite"],
  trim: ["start", "end", "duration", "overwrite"],
  split: ["time"],
  delete: ["start", "end"],
  set: ["volume", "rate", "track"],
  duplicate: ["at"],
};

export type MutationDecision =
  | { ok: true; after: string; nextStart: number; nextDuration: number }
  | { ok: false; reason: string; fix: string };

export interface MutationContext {
  ref: string;
  row: TimelineRow;
  before: string;
  resolved: Extract<ReturnType<typeof resolveRef>, { ok: true }>;
  parseTime: (expression: string) => ReturnType<typeof parseTimeExpression>;
  duration: number;
}

type ParsedMutationTime =
  | { ok: true; seconds: number }
  | { ok: false; reason: string; fix: string };

export const allRows = (timeline: ProjectTimeline): TimelineRow[] =>
  timeline.tracks.flatMap((track) => track.rows);

export function refusal(reason: string, fix: string, json: boolean): void {
  setCommandExitCode(2);
  const payload = { ok: false, reason, fix };
  console.error(json ? JSON.stringify(payload, null, 2) : `${reason}; ${fix}.`);
}

export const isFileChanged = (error: unknown): error is Error =>
  error instanceof Error && error.message === "file changed since the timeline was read";

export function refuse(kind: string, detail: { reason: string; fix: string }, json: boolean): void {
  refusal(`${kind}: ${detail.reason}`, detail.fix, json);
}

export function publicReceipt(receipt: AppliedFileMutation) {
  return {
    file: receipt.sourceFile,
    version: receipt.version,
    writeToken: receipt.writeToken,
    changed: receipt.changed,
    backupPath: receipt.backupPath,
  };
}

export function fpsFor(indexPath: string): number {
  const parsed = parseFpsWithDefault(
    readCompositionFps(readFileSync(indexPath, "utf-8")) ?? undefined,
  );
  return fpsToNumber(parsed.ok ? parsed.value : { num: 30, den: 1 });
}

export function declaredFps(source: string): number | null {
  const raw = readCompositionFps(source);
  if (raw === null) return null;
  const parsed = parseFpsWithDefault(raw);
  return parsed.ok ? fpsToNumber(parsed.value) : null;
}

function splitBaseId(row: TimelineRow): string {
  return row.ref.startsWith("hf:") ? row.ref.slice(3) : row.id;
}

function nextFreeSplitId(source: string, base: string): string {
  const document = new DOMParser().parseFromString(source, "text/html");
  const existing = new Set(Array.from(document.querySelectorAll("[id]"), (element) => element.id));
  const match = /^(.*)-(\d+)$/.exec(base);
  const prefix = match && existing.has(match[1]!) ? match[1]! : base;
  let suffix = 2;
  while (existing.has(`${prefix}-${suffix}`)) suffix += 1;
  return `${prefix}-${suffix}`;
}

function parseMutationTime(
  context: MutationContext,
  expression: string,
  fix: string,
): ParsedMutationTime {
  const value = context.parseTime(expression);
  if (!value.ok) return { ok: false, reason: value.reason, fix };
  if (value.seconds < 0 || value.seconds > context.duration) {
    return {
      ok: false,
      reason: `time ${value.seconds} is outside the composition duration`,
      fix: "pass a time between 0 and the composition duration",
    };
  }
  return { ok: true, seconds: value.seconds };
}

export function diff(before: string, after: string): string {
  if (before === after) return "";
  const beforeLines = before.split("\n");
  const afterLines = after.split("\n");
  let prefix = 0;
  while (
    prefix < beforeLines.length &&
    prefix < afterLines.length &&
    beforeLines[prefix] === afterLines[prefix]
  ) {
    prefix += 1;
  }
  let suffix = 0;
  while (
    suffix < beforeLines.length - prefix &&
    suffix < afterLines.length - prefix &&
    beforeLines[beforeLines.length - suffix - 1] === afterLines[afterLines.length - suffix - 1]
  ) {
    suffix += 1;
  }
  const changedBefore = beforeLines.slice(prefix, beforeLines.length - suffix);
  const changedAfter = afterLines.slice(prefix, afterLines.length - suffix);
  const lines = [
    "--- before",
    "+++ after",
    ...changedBefore.map((line) => `-${line}`),
    ...changedAfter.map((line) => `+${line}`),
  ];
  const output = lines.join("\n");
  return output.length <= 8_000 ? output : `${output.slice(0, 7_997)}...`;
}

function isAncestorOf(ancestor: TimelineRow, row: TimelineRow, timeline: ProjectTimeline): boolean {
  for (let pointer = row.parentRow; pointer; ) {
    const parent = rowAt(timeline, pointer);
    if (parent === ancestor) return true;
    pointer = parent.parentRow;
  }
  return false;
}

function sameLineage(a: TimelineRow, b: TimelineRow, timeline: ProjectTimeline): boolean {
  return isAncestorOf(a, b, timeline) || isAncestorOf(b, a, timeline);
}

function overlap(
  row: TimelineRow,
  timeline: ProjectTimeline,
  start: number,
  end: number,
): TimelineRow | undefined {
  return allRows(timeline).find(
    (candidate) =>
      candidate !== row &&
      !sameLineage(candidate, row, timeline) &&
      candidate.file === row.file &&
      candidate.trackIndex === row.trackIndex &&
      spansShareTime(start, end, candidate.start, candidate.end),
  );
}

function moveMutation(context: MutationContext, args: Record<string, unknown>): MutationDecision {
  const expression = typeof args.time === "string" ? args.time : "";
  const time = parseMutationTime(context, expression, "pass a valid time expression");
  if (!time.ok) return time;
  const end = time.seconds + context.row.duration;
  if (end > context.duration) {
    return {
      ok: false,
      reason: `move would end at ${end}, beyond composition duration ${context.duration}`,
      fix: `choose a start at or before the latest valid start ${context.duration - context.row.duration}`,
    };
  }
  const patched = patchElementInHtml(context.before, context.resolved.target, [
    { type: "html-attribute", property: "data-start", value: String(time.seconds) },
  ]);
  if (!patched.matched) {
    return { ok: false, reason: `${context.ref} was not found`, fix: "choose an existing clip" };
  }
  return {
    ok: true,
    after: patched.html,
    nextStart: time.seconds,
    nextDuration: context.row.duration,
  };
}

function splitMutation(context: MutationContext, args: Record<string, unknown>): MutationDecision {
  const expression = typeof args.time === "string" ? args.time : "";
  const time = parseMutationTime(context, expression, "pass a valid time expression");
  if (!time.ok) return time;
  const split = splitSource(
    context,
    context.before,
    context.resolved.target,
    time.seconds,
    context.row.duration,
  );
  if (!split.ok) return split;
  return {
    ok: true,
    after: split.html,
    nextStart: context.row.start,
    nextDuration: context.row.duration,
  };
}

function splitSource(
  context: MutationContext,
  source: string,
  target: SourceMutationTarget,
  seconds: number,
  duration: number,
): { ok: true; html: string; newId: string } | { ok: false; reason: string; fix: string } {
  const split = splitElementInHtml(
    source,
    target,
    seconds,
    nextFreeSplitId(source, splitBaseId(context.row)),
    { start: context.row.start, duration, track: context.row.trackIndex },
  );
  if (!split.matched || !split.newId) {
    return {
      ok: false,
      reason: `${context.ref} cannot be split at ${seconds}`,
      fix: "choose a time inside the clip",
    };
  }
  return { ok: true, html: split.html, newId: split.newId };
}

function trimMutation(context: MutationContext, args: Record<string, unknown>): MutationDecision {
  const bounds = trimBounds(context, args);
  if (!bounds.ok) return bounds;
  const patched = patchElementInHtml(context.before, context.resolved.target, [
    { type: "html-attribute", property: "data-start", value: String(bounds.nextStart) },
    { type: "html-attribute", property: "data-duration", value: String(bounds.nextDuration) },
  ]);
  if (!patched.matched) {
    return { ok: false, reason: `${context.ref} was not found`, fix: "choose an existing clip" };
  }
  return {
    ok: true,
    after: patched.html,
    nextStart: bounds.nextStart,
    nextDuration: bounds.nextDuration,
  };
}

function trimBounds(
  context: MutationContext,
  args: Record<string, unknown>,
): MutationDecision | { ok: true; nextStart: number; nextDuration: number } {
  const input = trimInput(args);
  if (!input.ok) return input;
  const start = trimStart(context, input.start);
  if (!start.ok) return start;
  return finishTrim(
    context,
    start.seconds,
    trimEnd(context, input.end),
    trimDuration(context, input.duration),
  );
}

function trimInput(args: Record<string, unknown>) {
  const input = {
    start: typeof args.start === "string" ? args.start : undefined,
    end: typeof args.end === "string" ? args.end : undefined,
    duration: typeof args.duration === "string" ? args.duration : undefined,
  };
  if (input.start || input.end || input.duration) return { ok: true as const, ...input };
  return {
    ok: false as const,
    reason: "trim requires --start, --end, or --duration",
    fix: "pass one trim option",
  };
}

const leavesNoLength = (start: number, duration: number) =>
  duration <= 0 || sameInstant(start, start + duration);

function finishTrim(
  context: MutationContext,
  nextStart: number,
  end: ReturnType<typeof trimEnd>,
  duration: ReturnType<typeof trimDuration>,
): MutationDecision | { ok: true; nextStart: number; nextDuration: number } {
  if (end && !end.ok) return end;
  if (duration && !duration.ok) return duration;
  const nextDuration =
    duration?.seconds ?? (end ? durationUntil(nextStart, end.seconds) : context.row.duration);
  if (leavesNoLength(nextStart, nextDuration)) {
    return {
      ok: false,
      reason: "trim duration must be positive",
      fix: "choose a later end or positive duration",
    };
  }
  return { ok: true, nextStart, nextDuration };
}

function trimStart(context: MutationContext, expression: string | undefined) {
  if (!expression) return { ok: true as const, seconds: context.row.start };
  return parseMutationTime(context, expression, "pass a valid time expression");
}

function durationUntil(start: number, end: number): number {
  let duration = end - start;
  while (duration > 0 && start + duration > end) duration = nextSmaller(duration);
  return duration;
}

const float = new DataView(new ArrayBuffer(8));
function nextSmaller(positive: number): number {
  float.setFloat64(0, positive);
  float.setBigUint64(0, float.getBigUint64(0) - 1n);
  return float.getFloat64(0);
}

function trimEnd(context: MutationContext, expression: string | undefined) {
  if (!expression) return undefined;
  return parseMutationTime(context, expression, "pass a valid time expression");
}

function trimDuration(context: MutationContext, expression: string | undefined) {
  if (!expression) return undefined;
  return parseMutationTime(context, expression, "pass a valid duration");
}

function deleteMutation(context: MutationContext, args: Record<string, unknown>): MutationDecision {
  const { row, resolved } = context;
  const range = deleteRange(context, args);
  if (!range.ok) return range;
  let html = context.before;
  if (!sameInstant(range.end, row.end)) {
    const tail = splitSource(context, html, resolved.target, range.end, row.duration);
    if (!tail.ok) return tail;
    html = tail.html;
  }
  let removed = resolved.target;
  if (!sameInstant(range.start, row.start)) {
    const middle = splitSource(context, html, resolved.target, range.start, range.end - row.start);
    if (!middle.ok) return middle;
    html = middle.html;
    removed = { id: middle.newId };
  }
  return {
    ok: true,
    after: removeElementFromHtml(html, removed),
    nextStart: row.start,
    nextDuration: row.duration,
  };
}

function deleteRange(
  context: MutationContext,
  args: Record<string, unknown>,
): { ok: true; start: number; end: number } | { ok: false; reason: string; fix: string } {
  const { row } = context;
  const bound = (value: unknown, fallback: number): ParsedMutationTime =>
    typeof value === "string"
      ? parseMutationTime(context, value, "pass a valid time expression")
      : { ok: true, seconds: fallback };
  const start = bound(args.start, row.start);
  if (!start.ok) return start;
  const end = bound(args.end, row.end);
  if (!end.ok) return end;
  const inside = (seconds: number) =>
    sameInstant(seconds, row.start) ||
    sameInstant(seconds, row.end) ||
    (seconds > row.start && seconds < row.end);
  if (!inside(start.seconds) || !inside(end.seconds)) {
    return {
      ok: false,
      reason: `delete range ${start.seconds}-${end.seconds} is not inside ${context.ref} (${row.start}-${row.end})`,
      fix: "pass --start and --end inside the clip",
    };
  }
  if (end.seconds <= start.seconds || sameInstant(start.seconds, end.seconds)) {
    return {
      ok: false,
      reason: "delete range must be positive",
      fix: "pass an --end later than --start",
    };
  }
  return { ok: true, start: start.seconds, end: end.seconds };
}

function setOperation(assignment: SetAssignment): PatchOperation {
  const property =
    assignment.field === "volume"
      ? "data-volume"
      : assignment.field === "rate"
        ? "data-playback-rate"
        : "data-track-index";
  return { type: "html-attribute", property, value: assignment.value };
}

function setMutation(context: MutationContext, args: Record<string, unknown>): MutationDecision {
  const positionalAssignments = positional(args)
    .slice(1)
    .filter((value): value is string => typeof value === "string");
  const namedAssignments = ["volume", "rate", "track"].flatMap((field) => {
    const value = args[field];
    return typeof value === "string" ? [`${field}=${value}`] : [];
  });
  const assignments = parseSetAssignments([...positionalAssignments, ...namedAssignments]);
  if (!assignments.ok) return assignments;
  const patched = patchElementInHtml(
    context.before,
    context.resolved.target,
    assignments.assignments.map(setOperation),
  );
  if (!patched.matched) {
    return { ok: false, reason: `${context.ref} was not found`, fix: "choose an existing clip" };
  }
  return {
    ok: true,
    after: patched.html,
    nextStart: context.row.start,
    nextDuration: context.row.duration,
  };
}

function duplicateMutation(
  context: MutationContext,
  args: Record<string, unknown>,
): MutationDecision {
  const expression = typeof args.at === "string" ? args.at : String(context.row.end);
  const time = parseMutationTime(context, expression, "pass a valid insertion time");
  if (!time.ok) return time;
  const duplicate = duplicateElementInHtml(
    context.before,
    context.resolved.target,
    `${splitBaseId(context.row)}-copy`,
    time.seconds,
  );
  if (!duplicate.matched) {
    return { ok: false, reason: `${context.ref} was not found`, fix: "choose an existing clip" };
  }
  return {
    ok: true,
    after: duplicate.html,
    nextStart: time.seconds,
    nextDuration: context.row.duration,
  };
}

export function decideMutation(
  verb: MutationVerb,
  context: MutationContext,
  args: Record<string, unknown>,
): MutationDecision {
  switch (verb) {
    case "move":
      return moveMutation(context, args);
    case "trim":
      return trimMutation(context, args);
    case "split":
      return splitMutation(context, args);
    case "delete":
      return deleteMutation(context, args);
    case "set":
      return setMutation(context, args);
    case "duplicate":
      return duplicateMutation(context, args);
  }
}

export function rowAt(
  timeline: ProjectTimeline,
  pointer: { kind: TimelineRow["trackKind"]; index: number },
): TimelineRow {
  const track = timeline.tracks.find((candidate) => candidate.kind === pointer.kind);
  if (!track) throw new Error(`missing track ${pointer.kind}`);
  const row = track.rows[pointer.index];
  if (!row) throw new Error(`missing row ${pointer.kind}/${pointer.index}`);
  return row;
}

export function positional(args: Record<string, unknown>): string[] {
  return Array.isArray(args._)
    ? args._.filter((value): value is string => typeof value === "string")
    : [];
}

export function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null && !Array.isArray(value);
}

export function mutationConflict(
  verb: MutationVerb,
  overwrite: boolean,
  row: TimelineRow,
  timeline: ProjectTimeline,
  nextStart: number,
  nextDuration: number,
): { reason: string; fix: string } | null {
  if (verb === "duplicate") {
    const conflict = allRows(timeline).find(
      (candidate) =>
        !sameLineage(candidate, row, timeline) &&
        candidate.file === row.file &&
        candidate.trackIndex === row.trackIndex &&
        isInsideSpan(nextStart, candidate.start, candidate.end),
    );
    if (!conflict) return null;
    return {
      reason: `duplicate insertion at ${nextStart} falls inside ${conflict.ref}`,
      fix: "choose a clip boundary or split the spanning clip first",
    };
  }
  if ((verb !== "move" && verb !== "trim") || overwrite) return null;
  const conflict = overlap(row, timeline, nextStart, nextStart + nextDuration);
  if (!conflict) return null;
  return {
    reason: `${row.ref} would overlap ${conflict.ref} at ${nextStart}-${nextStart + nextDuration}`,
    fix: "pass --overwrite or move the named neighbour",
  };
}