Skip to content

Write HTML. Render video. Built for agents.

33.5 KB
Raw Blame
import { spawnSync } from "node:child_process";
import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import { isClipVisibleAt } from "@hyperframes/core";
import { describe, expect, it } from "vitest";

const cliEntry = resolve(fileURLToPath(import.meta.url), "..", "..", "cli.ts");

function project(): string {
  const dir = mkdtempSync(join(tmpdir(), "hf-timeline-cli-"));
  writeFileSync(
    join(dir, "index.html"),
    `<div data-composition-id="main" data-duration="12"><div id="clip" data-hf-id="clip" data-start="1" data-duration="2" data-track-index="0"></div><div id="neighbour" data-hf-id="neighbour" data-start="5" data-duration="2" data-track-index="0"></div></div>`,
  );
  return dir;
}

function batchProject() {
  const dir = project();
  mkdirSync(join(dir, "compositions"));
  writeFileSync(
    join(dir, "index.html"),
    `<div data-composition-id="main" data-duration="12"><div id="clip" data-hf-id="clip" data-start="1" data-duration="2" data-track-index="0"></div><div id="scene" data-composition-id="scene" data-composition-src="compositions/scene.html" data-start="0" data-duration="4" data-track-index="1"></div></div>`,
  );
  writeFileSync(
    join(dir, "compositions/scene.html"),
    `<div data-composition-id="scene"><div id="nested" data-hf-id="nested" data-start="0" data-duration="2" data-track-index="0"></div></div>`,
  );
  const files = ["index.html", "compositions/scene.html"];
  const sources = () => files.map((file) => readFileSync(join(dir, file), "utf8"));
  const before = sources();
  const planPath = join(dir, "edits.json");
  writeFileSync(
    planPath,
    JSON.stringify([
      { verb: "set", ref: "#clip", volume: "0.25" },
      { verb: "set", ref: "#nested", volume: "0.5" },
    ]),
  );
  return { dir, files, sources, before, planPath };
}

function run(dir: string, ...args: string[]) {
  return spawnSync(
    "bun",
    ["run", cliEntry, "timeline", args[0]!, "--dir", dir, "--json", ...args.slice(1)],
    {
      cwd: dir,
      encoding: "utf8",
      timeout: 30_000,
      env: { ...process.env, HYPERFRAMES_SKIP_UPDATE_CHECK: "1" },
    },
  );
}

describe("timeline project inspection", () => {
  it.each([
    { name: "absolute", directory: "absolute", json: true, flagFirst: false },
    { name: "relative", directory: "relative", json: true, flagFirst: false },
    { name: "JSON before directory", directory: "absolute", json: true, flagFirst: true },
    { name: "text", directory: "relative", json: false, flagFirst: false },
    { name: "subcommand-named directory", directory: "move", json: true, flagFirst: false },
    { name: "literal subcommand name", directory: "literalMove", json: true, flagFirst: false },
  ])("inspects a $name project from another directory", ({ directory, json, flagFirst }) => {
    const parent = mkdtempSync(join(tmpdir(), "hf-timeline-inspect-"));
    try {
      const name =
        directory === "move" || directory === "literalMove" ? "move" : "project with spaces";
      const target = join(parent, name);
      mkdirSync(target);
      const source =
        '<div data-composition-id="main" data-duration="7"><div id="chosen-project" data-start="1" data-duration="2"></div></div>';
      writeFileSync(join(target, "index.html"), source);
      const argument = directory === "absolute" ? target : `./${name}`;
      const args =
        directory === "literalMove"
          ? ["--json", "--", "move"]
          : json
            ? flagFirst
              ? ["--json", argument]
              : [argument, "--json"]
            : [argument];
      const result = spawnSync("bun", ["run", cliEntry, "timeline", ...args], {
        cwd: parent,
        encoding: "utf8",
        timeout: 30_000,
        env: { ...process.env, HYPERFRAMES_SKIP_UPDATE_CHECK: "1" },
      });
      expect(result.status, result.stderr).toBe(0);
      if (json) {
        const output: unknown = JSON.parse(result.stdout);
        expect(output).toMatchObject({
          timeline: { duration: 7, tracks: [{ rows: [{ id: "chosen-project" }] }] },
        });
      } else {
        expect(result.stdout).toContain("timeline 7s");
        expect(result.stdout).toContain("#chosen-project chosen-project 1-3s");
      }
      expect(readFileSync(join(target, "index.html"), "utf8")).toBe(source);
    } finally {
      rmSync(parent, { recursive: true, force: true });
    }
  });

  it.each([
    { args: ["--json", "--unknown-option"], diagnostic: "Unknown flag: --unknown-option" },
    { args: ["--json", "extra-project"], diagnostic: "Unexpected extra argument" },
    { args: ["--", "extra-project"], diagnostic: "Unexpected extra argument" },
  ])("keeps inspection argument validation for $diagnostic", ({ args, diagnostic }) => {
    const dir = project();
    const source = readFileSync(join(dir, "index.html"), "utf8");
    try {
      const result = spawnSync("bun", ["run", cliEntry, "timeline", dir, ...args], {
        cwd: dir,
        encoding: "utf8",
        timeout: 30_000,
        env: { ...process.env, HYPERFRAMES_SKIP_UPDATE_CHECK: "1" },
      });
      expect(result.status).not.toBe(0);
      expect(result.stderr + result.stdout).toContain(diagnostic);
      expect(readFileSync(join(dir, "index.html"), "utf8")).toBe(source);
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });
});

describe("timeline edit command", () => {
  it.each([
    ["move", ["#clip", "+1"], 'data-start="2"'],
    ["trim", ["#clip", "--duration", "1"], 'data-duration="1"'],
    ["split", ["#clip", "2"], 'id="clip-2"'],
    ["delete", ["#clip"], 'id="clip"'],
  ])("executes %s against a temp project", (verb, args, marker) => {
    const dir = project();
    try {
      const result = run(dir, verb, ...args);
      expect(result.status, result.stderr).toBe(0);
      const output = JSON.parse(result.stdout) as {
        before: Array<{ ref: string }>;
        after: Array<{ ref: string; start: number; duration: number }>;
      };
      expect(output).toMatchObject({
        ok: true,
        receipt: expect.any(Object),
      });
      expect(output.before.some((row) => row.ref === "#clip")).toBe(true);
      const clipAfter = output.after.find((row) => row.ref === "#clip");
      if (verb === "move") expect(clipAfter).toMatchObject({ start: 2 });
      if (verb === "trim") expect(clipAfter).toMatchObject({ duration: 1 });
      if (verb === "split") expect(output.after).toHaveLength(3);
      if (verb === "delete") expect(clipAfter).toBeUndefined();
      const html = readFileSync(join(dir, "index.html"), "utf8");
      if (verb === "delete") expect(html).not.toContain('id="clip"');
      else expect(html).toContain(marker);
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  it("runs an edit subcommand whose clip reference follows an argument separator", () => {
    const dir = project();
    try {
      const result = run(dir, "move", "--plan", "--", "#clip", "+1");
      expect(result.status, result.stderr).toBe(0);
      const output: unknown = JSON.parse(result.stdout);
      expect(output).toMatchObject({
        ok: true,
        planned: true,
        after: expect.arrayContaining([expect.objectContaining({ ref: "#clip", start: 2 })]),
      });
      expect(readFileSync(join(dir, "index.html"), "utf8")).toContain('data-start="1"');
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  it("names an id-less hf ref split from its stable id", () => {
    const dir = project();
    try {
      const indexPath = join(dir, "index.html");
      writeFileSync(indexPath, readFileSync(indexPath, "utf8").replace('id="clip"', ""));
      const result = run(dir, "split", "hf:clip", "2");
      expect(result.status, result.stderr).toBe(0);
      expect(readFileSync(indexPath, "utf8")).toContain('id="clip-2"');
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  it("keeps a sub-composition's place in both halves of a split", () => {
    const dir = mkdtempSync(join(tmpdir(), "hf-timeline-split-host-"));
    try {
      writeFileSync(
        join(dir, "index.html"),
        `<div data-composition-id="main" data-duration="12"><div id="host" data-composition-src="sub.html" data-start="1" data-duration="4" data-track-index="0"></div></div>`,
      );
      writeFileSync(
        join(dir, "sub.html"),
        `<div data-composition-id="sub" data-duration="4"><div id="inner" data-start="0" data-duration="4"></div></div>`,
      );
      const result = run(dir, "split", "#host", "3");
      expect(result.status, result.stderr).toBe(0);
      const html = readFileSync(join(dir, "index.html"), "utf8");
      const tag = (id: string) => html.match(new RegExp(`<[^>]*\\sid="${id}"[^>]*>`))?.[0];
      expect(tag("host")).toContain('data-playback-start="0"');
      expect(tag("host-2")).toContain('data-playback-start="2"');
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  it("deletes only the --start/--end range of a video clip, keeping both sides", () => {
    const dir = mkdtempSync(join(tmpdir(), "hf-timeline-range-delete-"));
    try {
      const indexPath = join(dir, "index.html");
      writeFileSync(
        indexPath,
        `<div data-composition-id="main" data-duration="12"><video id="clip" src="a.mp4" data-start="1" data-duration="4" data-track-index="0"></video></div>`,
      );
      const planned = run(dir, "delete", "#clip", "--start", "2", "--end", "3", "--plan");
      expect(planned.status, planned.stderr).toBe(0);
      const kept = [
        expect.objectContaining({ ref: "#clip", start: 1, end: 2 }),
        expect.objectContaining({ ref: "#clip-2", start: 3, end: 5 }),
      ];
      expect(JSON.parse(planned.stdout).after).toEqual(kept);
      const applied = run(dir, "delete", "#clip", "--start", "2", "--end", "3");
      expect(applied.status, applied.stderr).toBe(0);
      expect(JSON.parse(applied.stdout).after).toEqual(kept);
      const html = readFileSync(indexPath, "utf8");
      const tag = (id: string) => html.match(new RegExp(`<[^>]*\\sid="${id}"[^>]*>`))?.[0];
      expect(tag("clip-2")).toContain('data-media-start="2"');
      expect(html).not.toContain('id="clip-3"');
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  it("refuses a delete range that reaches outside the clip, without writing", () => {
    const dir = project();
    try {
      const before = readFileSync(join(dir, "index.html"), "utf8");
      const result = run(dir, "delete", "#clip", "--start", "2", "--end", "4");
      expect(result.status).toBe(2);
      expect(result.stderr).toContain("is not inside #clip");
      expect(readFileSync(join(dir, "index.html"), "utf8")).toBe(before);
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  it.each([
    ["--at", ["delete", "#clip", "--at", "2"]],
    ["--start", ["split", "#clip", "2", "--start", "1"]],
    ["--duration", ["move", "#clip", "+1", "--duration", "1"]],
    ["--overwrite", ["duplicate", "#clip", "--overwrite"]],
    ["--end", ["set", "#clip", "volume=0.5", "--end", "2"]],
  ])("refuses a flag its verb does not use (%s), without writing", (flag, args) => {
    const dir = project();
    try {
      const before = readFileSync(join(dir, "index.html"), "utf8");
      const result = run(dir, ...args);
      expect(result.status).not.toBe(0);
      expect(result.stderr).toContain(`Unknown flag: ${flag}`);
      expect(readFileSync(join(dir, "index.html"), "utf8")).toBe(before);
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  it("refuses an apply edit with a key its verb does not use, without writing", () => {
    const dir = project();
    try {
      const before = readFileSync(join(dir, "index.html"), "utf8");
      const planPath = join(dir, "edits.json");
      writeFileSync(planPath, JSON.stringify([{ verb: "delete", ref: "#clip", at: "2" }]));
      const result = run(dir, "apply", planPath);
      expect(result.status).toBe(2);
      expect(result.stderr).toContain("delete does not use at");
      expect(readFileSync(join(dir, "index.html"), "utf8")).toBe(before);
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  it("uses the next free numeric split suffix on repeat", () => {
    const dir = project();
    try {
      const first = run(dir, "split", "#clip", "1.5");
      expect(first.status, first.stderr).toBe(0);
      const second = run(dir, "split", "#clip-2", "2.5");
      expect(second.status, second.stderr).toBe(0);
      const html = readFileSync(join(dir, "index.html"), "utf8");
      expect(html).toContain('id="clip-2"');
      expect(html).toContain('id="clip-3"');
      expect(html).not.toContain('id="clip-2-2"');
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  it("refuses overlap", () => {
    const dir = project();
    try {
      const result = run(dir, "move", "#clip", "4");
      expect(result.status).toBe(2);
      expect(result.stderr).toContain("--overwrite");
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  const meeting = (aStart: string, aDuration: string, bStart: string, fps = "") =>
    `<div data-composition-id="main"${fps} data-duration="40"><div id="a" data-hf-id="a" data-start="${aStart}" data-duration="${aDuration}" data-track-index="0"></div><div id="b" data-hf-id="b" data-start="${bStart}" data-duration="2" data-track-index="0"></div></div>`;
  const clip = (html: string, id: string) => {
    const tag = new RegExp(`<div[^>]*\\sid="${id}"[^>]*>`).exec(html)?.[0] ?? "";
    const attr = (name: string) => new RegExp(`${name}="([^"]+)"`).exec(tag)?.[1];
    return { start: attr("data-start"), duration: attr("data-duration") };
  };
  const endOf = (html: string, id: string) =>
    Number(clip(html, id).start) + Number(clip(html, id).duration);

  it.each([
    ["moves a hidden clip into its wrapper's window", ["move", "#lost", "8"], "lost", "8"],
    ["moves a wrapper without colliding with its own clips", ["move", "#shot2", "4"], "shot2", "4"],
    ["duplicates a clip inside its wrapper", ["duplicate", "#seen"], "seen", "6"],
  ])("%s", (_name, args, id, start) => {
    const dir = mkdtempSync(join(tmpdir(), "hf-timeline-nested-"));
    writeFileSync(
      join(dir, "index.html"),
      `<div data-composition-id="main" data-duration="12"><div id="shot2" data-hf-id="shot2" data-start="5" data-duration="5" data-track-index="0"><div id="seen" data-hf-id="seen" data-start="6" data-duration="2">In</div><div id="lost" data-hf-id="lost" data-start="0" data-duration="2">Out</div></div></div>`,
    );
    try {
      const result = run(dir, ...args);
      expect(result.stderr).not.toContain("overlap");
      expect(result.status).toBe(0);
      expect(clip(readFileSync(join(dir, "index.html"), "utf8"), id).start).toBe(start);
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  const visibleAt = (html: string, time: number, ids: string[]) =>
    ids.filter((id) => isClipVisibleAt(time, Number(clip(html, id).start), endOf(html, id), 40));

  const composition = (fps: string, ...clips: [string, string, string][]) =>
    `<div data-composition-id="main"${fps} data-duration="40">${clips
      .map(
        ([id, start, duration]) =>
          `<div id="${id}" data-hf-id="${id}" data-start="${start}" data-duration="${duration}" data-track-index="0"></div>`,
      )
      .join("")}</div>`;

  it.each([
    [
      "move",
      ["#b", "20f"],
      composition(' data-fps="24"', ["a", "0", String(20 / 24 + 5e-7)], ["b", "2", "0.25"]),
    ],
    ["duplicate", ["#c", "--at", "1"], composition("", ["a", "0", "1.0000005"], ["c", "3", "1"])],
  ])("refuses a %s that lands half a microsecond inside another clip", (verb, args, html) => {
    const dir = project();
    try {
      writeFileSync(join(dir, "index.html"), html);
      expect(run(dir, verb, ...args).status).not.toBe(0);
      expect(readFileSync(join(dir, "index.html"), "utf8")).toBe(html);
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  it.each([
    [
      "a clip wholly before the insertion point",
      ["#x", "--at", "5"],
      composition("", ["x", "0", "1"], ["t", "4.9999995", "0.0000002"]),
      4.9999995,
    ],
    [
      "a clip half a microsecond after it",
      ["#a"],
      composition("", ["a", "0", "1"], ["t", "1.0000005", "1"]),
      1.0000005 + 1,
    ],
  ])("duplicates without snapping %s to the copy", (_, args, html, tStart) => {
    const dir = project();
    try {
      writeFileSync(join(dir, "index.html"), html);
      expect(run(dir, "duplicate", ...args).status).toBe(0);
      expect(Number(clip(readFileSync(join(dir, "index.html"), "utf8"), "t").start)).toBe(tStart);
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  it("trims a clip that only meets the one before it, ending where asked", () => {
    const dir = project();
    try {
      writeFileSync(join(dir, "index.html"), meeting("19.8", "6.4", "26.2"));
      expect(run(dir, "trim", "#b", "--end", "29").status).toBe(0);
      const html = readFileSync(join(dir, "index.html"), "utf8");
      expect(clip(html, "b")).toEqual({ start: "26.2", duration: "2.8000000000000007" });
      expect(endOf(html, "b")).toBe(29);
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  it("trims up to the next clip's start without ending past it, where no duration lands exactly", () => {
    const dir = project();
    try {
      writeFileSync(join(dir, "index.html"), meeting("4.74", "10", "25.74"));
      expect(run(dir, "trim", "#a", "--end", "25.74").status).toBe(0);
      const html = readFileSync(join(dir, "index.html"), "utf8");
      expect(endOf(html, "a")).toBeLessThanOrEqual(25.74);
      expect(visibleAt(html, 25.74, ["a", "b"])).toEqual(["b"]);
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  it("trims to frame 20 at 30 fps so that frame shows the next clip and not this one", () => {
    const dir = project();
    try {
      writeFileSync(join(dir, "index.html"), meeting("0", "2", "2", ' data-fps="30"'));
      expect(run(dir, "trim", "#a", "--end", "20f").status).toBe(0);
      expect(run(dir, "trim", "#b", "--start", "20f").status).toBe(0);
      const html = readFileSync(join(dir, "index.html"), "utf8");
      expect([clip(html, "a").duration, clip(html, "b").start]).toEqual([
        "0.6666666666666666",
        "0.6666666666666666",
      ]);
      expect(visibleAt(html, 19 / 30, ["a", "b"])).toEqual(["a"]);
      expect(visibleAt(html, 20 / 30, ["a", "b"])).toEqual(["b"]);
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  it.each([
    ["19.8", "6.4", "26.2"],
    ["0", "0.6666666666666666", "0.6666666666666666"],
    ["0.1", "1.1", "1.2"],
  ])(
    "duplicates a clip at %s lasting %s up against the clip at %s, each boundary exact",
    (aStart, aDuration, bStart) => {
      const dir = project();
      try {
        writeFileSync(join(dir, "index.html"), meeting(aStart, aDuration, bStart));
        expect(run(dir, "duplicate", "#a").status).toBe(0);
        const html = readFileSync(join(dir, "index.html"), "utf8");
        const ids = ["a", "a-copy", "b"];
        expect(Number(clip(html, "a-copy").start)).toBe(endOf(html, "a"));
        expect(Number(clip(html, "b").start)).toBe(endOf(html, "a-copy"));
        expect(visibleAt(html, endOf(html, "a"), ids)).toEqual(["a-copy"]);
        expect(visibleAt(html, endOf(html, "a-copy"), ids)).toEqual(["b"]);
      } finally {
        rmSync(dir, { recursive: true, force: true });
      }
    },
  );

  it("refuses an ambiguous reference", () => {
    const dir = project();
    try {
      writeFileSync(
        join(dir, "index.html"),
        `<div data-composition-id="main"><div id="dup" data-start="1" data-duration="2" data-track-index="0"></div><div id="dup" data-start="5" data-duration="2" data-track-index="0"></div></div>`,
      );
      const result = run(dir, "delete", "#dup");
      expect(result.status).toBe(2);
      expect(result.stderr).toContain("matches 2 rows");
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  it("refuses snap when the project fps is unknown", () => {
    const dir = project();
    try {
      const result = run(dir, "move", "#clip", "1.03", "--snap");
      expect(result.status).toBe(2);
      expect(result.stderr).toContain("set data-fps");
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  it("refuses a move whose clip would end beyond the composition", () => {
    const dir = mkdtempSync(join(tmpdir(), "hf-timeline-move-bound-"));
    try {
      const indexPath = join(dir, "index.html");
      writeFileSync(
        indexPath,
        `<div data-composition-id="main" data-duration="53"><div id="clip" data-start="1" data-duration="10" data-track-index="0"></div></div>`,
      );
      const result = run(dir, "move", "#clip", "50");
      expect(result.status).toBe(2);
      expect(result.stderr).toContain("end at 60");
      expect(result.stderr).toContain("latest valid start 43");
      expect(readFileSync(indexPath, "utf8")).toContain('data-start="1"');
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  it("snaps a known project fps to one frame", () => {
    const dir = project();
    try {
      const indexPath = join(dir, "index.html");
      writeFileSync(
        indexPath,
        readFileSync(indexPath, "utf8").replace(
          'data-composition-id="main"',
          'data-composition-id="main" data-fps="10"',
        ),
      );
      const result = run(dir, "move", "#clip", "1.06", "--snap");
      expect(result.status, result.stderr).toBe(0);
      const output = JSON.parse(result.stdout) as {
        after: Array<{ ref: string; start: number }>;
      };
      expect(output.after.find((row) => row.ref === "#clip")).toMatchObject({
        start: 1.1,
      });
      expect(readFileSync(join(dir, "index.html"), "utf8")).toContain('data-start="1.1"');
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  it("uses the nested composition duration for time bounds", () => {
    const dir = mkdtempSync(join(tmpdir(), "hf-timeline-nested-"));
    try {
      writeFileSync(
        join(dir, "index.html"),
        `<div data-composition-id="main" data-duration="60"><div id="host" data-composition-src="sub.html" data-start="10" data-duration="3" data-track-index="0"></div></div>`,
      );
      writeFileSync(
        join(dir, "sub.html"),
        `<div data-composition-id="sub" data-duration="3"><div id="inner" data-start="0" data-duration="1" data-track-index="0"></div></div>`,
      );
      const result = run(dir, "move", "#inner", "45");
      expect(result.status).toBe(2);
      expect(result.stderr).toContain("composition duration");
      expect(readFileSync(join(dir, "sub.html"), "utf8")).toContain('data-start="0"');
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  it("keeps --plan JSON aligned with applied JSON and does not write", () => {
    const plannedDir = project();
    const appliedDir = project();
    try {
      const before = readFileSync(join(plannedDir, "index.html"), "utf8");
      const planned = run(plannedDir, "move", "#clip", "+1", "--plan");
      expect(planned.status, planned.stderr).toBe(0);
      const planJson = JSON.parse(planned.stdout) as Record<string, unknown>;
      expect(planJson.planned).toBe(true);
      expect(readFileSync(join(plannedDir, "index.html"), "utf8")).toBe(before);

      const applied = run(appliedDir, "move", "#clip", "+1");
      expect(applied.status, applied.stderr).toBe(0);
      const appliedJson = JSON.parse(applied.stdout) as Record<string, unknown>;
      expect(appliedJson.planned).toBe(false);
      expect(Object.keys(planJson).sort()).toEqual(Object.keys(appliedJson).sort());
      expect(appliedJson.receipt).toMatchObject({ file: "index.html", changed: true });
    } finally {
      rmSync(plannedDir, { recursive: true, force: true });
      rmSync(appliedDir, { recursive: true, force: true });
    }
  });

  it("stamps stable ids with ids", () => {
    const dir = project();
    try {
      const indexPath = join(dir, "index.html");
      writeFileSync(indexPath, readFileSync(indexPath, "utf8").replace(/ data-hf-id="[^"]+"/g, ""));
      const result = run(dir, "ids");
      expect(result.status, result.stderr).toBe(0);
      expect(readFileSync(indexPath, "utf8")).toMatch(/data-hf-id=/);
      const output = JSON.parse(result.stdout) as { after: Array<{ ref: string }> };
      expect(output.after.some((row) => row.ref === "#clip")).toBe(true);
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  it("sets clip attributes", () => {
    const dir = project();
    try {
      const result = run(dir, "set", "#clip", "volume=0.4", "rate=1.5", "track=2");
      expect(result.status, result.stderr).toBe(0);
      const html = readFileSync(join(dir, "index.html"), "utf8");
      expect(html).toContain('data-volume="0.4"');
      expect(html).toContain('data-playback-rate="1.5"');
      expect(html).toContain('data-track-index="2"');
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  it("duplicates with insert-and-ripple", () => {
    const dir = project();
    try {
      const result = run(dir, "duplicate", "#clip", "--at", "3");
      expect(result.status, result.stderr).toBe(0);
      const html = readFileSync(join(dir, "index.html"), "utf8");
      expect(html).toContain('id="clip-copy"');
      expect(html.match(/data-hf-id=/g)).toHaveLength(4);
      expect(html).toContain('id="neighbour" data-hf-id="neighbour" data-start="7"');
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  it("refuses a trim that would leave a clip one float rounding step long", () => {
    const dir = mkdtempSync(join(tmpdir(), "hf-timeline-cli-"));
    try {
      const indexPath = join(dir, "index.html");
      writeFileSync(indexPath, meeting("19.8", "6.4", "26.2"));
      const result = run(dir, "trim", "#b", "--end", "26.200000000000003");
      expect(result.status).toBe(2);
      expect(result.stderr).toContain("trim duration must be positive");
      expect(clip(readFileSync(indexPath, "utf8"), "b").duration).toBe("2");
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  it("moves a clip over pending media, whose unknown length counts as zero", () => {
    const dir = mkdtempSync(join(tmpdir(), "hf-timeline-cli-"));
    try {
      const indexPath = join(dir, "index.html");
      writeFileSync(
        indexPath,
        `<div data-composition-id="main" data-duration="12"><div id="a" data-hf-id="a" data-start="3" data-duration="1" data-track-index="0"></div><video id="pending" data-hf-id="pending" src="https://example.com/v.mp4" data-start="1" data-track-index="0"></video></div>`,
      );
      const result = run(dir, "move", "#a", "0.5");
      expect(result.status, result.stderr).toBe(0);
      expect(clip(readFileSync(indexPath, "utf8"), "a").start).toBe("0.5");
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  it("refuses duplicate insertion inside a spanning clip", () => {
    const dir = project();
    try {
      const indexPath = join(dir, "index.html");
      writeFileSync(
        indexPath,
        readFileSync(indexPath, "utf8").replace('data-duration="2"', 'data-duration="4"'),
      );
      const result = run(dir, "duplicate", "#clip", "--at", "3");
      expect(result.status).toBe(2);
      expect(result.stderr).toContain("split the spanning clip first");
      expect(readFileSync(indexPath, "utf8")).not.toContain('id="clip-copy"');
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  it("revalidates each apply edit against the previous edit's source", () => {
    const dir = project();
    try {
      const indexPath = join(dir, "index.html");
      writeFileSync(
        indexPath,
        readFileSync(indexPath, "utf8").replace('data-start="5"', 'data-start="7"'),
      );
      const planPath = join(dir, "edits.json");
      writeFileSync(
        planPath,
        JSON.stringify([
          { verb: "move", ref: "#clip", time: "+1" },
          { verb: "move", ref: "#clip", time: "+2" },
        ]),
      );
      const result = run(dir, "apply", planPath);
      expect(result.status, result.stderr).toBe(0);
      expect(readFileSync(indexPath, "utf8")).toContain('data-start="4"');
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  it("applies a JSON plan atomically and undoes its receipt", () => {
    const dir = project();
    try {
      const planPath = join(dir, "edits.json");
      writeFileSync(planPath, JSON.stringify([{ verb: "set", ref: "#clip", volume: "0.25" }]));
      const before = readFileSync(join(dir, "index.html"), "utf8");
      const planned = run(dir, "apply", planPath, "--plan");
      expect(planned.status, planned.stderr).toBe(0);
      expect(JSON.parse(planned.stdout)).toMatchObject({ ok: true, planned: true });
      expect(readFileSync(join(dir, "index.html"), "utf8")).toBe(before);

      const applied = run(dir, "apply", planPath);
      expect(applied.status, applied.stderr).toBe(0);
      const appliedJson = JSON.parse(applied.stdout) as { receipt: Array<Record<string, unknown>> };
      expect(readFileSync(join(dir, "index.html"), "utf8")).toContain('data-volume="0.25"');
      const undone = run(dir, "undo", JSON.stringify(appliedJson.receipt[0]));
      expect(undone.status, undone.stderr).toBe(0);
      expect(readFileSync(join(dir, "index.html"), "utf8")).toBe(before);
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  it.each(["response", "array", "file"])(
    "undoes all files in an apply receipt passed as a %s and returns a redo receipt",
    (format) => {
      const { dir, files, sources, before, planPath } = batchProject();
      try {
        const applied = run(dir, "apply", planPath);
        expect(applied.status, applied.stderr).toBe(0);
        const appliedJson: { receipt: Array<Record<string, unknown>> } = JSON.parse(applied.stdout);
        expect(appliedJson.receipt).toHaveLength(2);
        const after = sources();
        expect(after[0]).toContain('data-volume="0.25"');
        expect(after[1]).toContain('data-volume="0.5"');
        let input = format === "array" ? JSON.stringify(appliedJson.receipt) : applied.stdout;
        if (format === "file") {
          input = join(dir, "receipt.json");
          writeFileSync(input, applied.stdout);
        }

        const undone = run(dir, "undo", input);
        expect(undone.status, undone.stderr).toBe(0);
        expect(JSON.parse(undone.stdout)).toMatchObject({ ok: true, file: files });
        expect(sources()).toEqual(before);

        const redone = run(dir, "undo", undone.stdout);
        expect(redone.status, redone.stderr).toBe(0);
        expect(sources()).toEqual(after);
      } finally {
        rmSync(dir, { recursive: true, force: true });
      }
    },
  );

  it.each(["stale", "invalid"])(
    "leaves the whole undo batch untouched when a later receipt is %s",
    (failure) => {
      const { dir, sources, planPath } = batchProject();
      try {
        const applied = run(dir, "apply", planPath);
        expect(applied.status, applied.stderr).toBe(0);
        const appliedJson: { receipt: Array<Record<string, unknown>> } = JSON.parse(applied.stdout);
        if (failure === "stale") {
          const childPath = join(dir, "compositions/scene.html");
          writeFileSync(childPath, readFileSync(childPath, "utf8") + "<!-- newer edit -->");
        }
        const current = sources();
        const input =
          failure === "stale"
            ? applied.stdout
            : JSON.stringify([appliedJson.receipt[0], { file: "bad" }]);

        const undone = run(dir, "undo", input);
        expect(undone.status).toBe(2);
        expect(JSON.parse(undone.stderr)).toMatchObject({
          ok: false,
          reason:
            failure === "stale"
              ? "file changed since the timeline was read"
              : "timeline undo: undo receipt is missing file, version, or backupPath",
        });
        expect(sources()).toEqual(current);
      } finally {
        rmSync(dir, { recursive: true, force: true });
      }
    },
  );

  it("undoes a complete timeline ids response", () => {
    const dir = project();
    try {
      const indexPath = join(dir, "index.html");
      const before = readFileSync(indexPath, "utf8").replace(/ data-hf-id="[^"]*"/g, "");
      writeFileSync(indexPath, before);
      const stamped = run(dir, "ids");
      expect(stamped.status, stamped.stderr).toBe(0);
      expect(readFileSync(indexPath, "utf8")).toContain("data-hf-id=");

      const undone = run(dir, "undo", stamped.stdout);
      expect(undone.status, undone.stderr).toBe(0);
      expect(readFileSync(indexPath, "utf8")).toBe(before);
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  it("accepts an empty receipt from an unchanged apply", () => {
    const dir = project();
    try {
      const before = readFileSync(join(dir, "index.html"), "utf8");
      const planPath = join(dir, "edits.json");
      writeFileSync(planPath, "[]");
      const applied = run(dir, "apply", planPath);
      expect(applied.status, applied.stderr).toBe(0);

      const undone = run(dir, "undo", applied.stdout);
      expect(undone.status, undone.stderr).toBe(0);
      expect(JSON.parse(undone.stdout)).toMatchObject({ ok: true, receipt: [], file: [] });
      expect(readFileSync(join(dir, "index.html"), "utf8")).toBe(before);
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });
});