Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
fix(cli): timeline delete --start/--end removes only that range (#5867)
Miguel Ángeld2b8ea764431
diff --git a/docs/packages/cli.mdx b/docs/packages/cli.mdxindex c64636273c..b99c64f791 100644--- a/docs/packages/cli.mdx+++ b/docs/packages/cli.mdx@@ -1125,6 +1125,7 @@ npx hyperframes timeline split '#outro' 6.5npx hyperframes timeline set '#music' volume=0.5npx hyperframes timeline duplicate '#intro' --at 3npx hyperframes timeline delete '#outro' --json+npx hyperframes timeline delete '#outro' --start 6 --end 7 # cut one second out```| Command | What it does |@@ -1132,7 +1133,7 @@ npx hyperframes timeline delete '#outro' --json| `move <ref> <time>` | Start the clip at `<time>`, keeping its length || `trim <ref>` | Change the clip's `--start`, `--end`, or `--duration` (at least one) || `split <ref> <time>` | Cut the clip in two at `<time>` |-| `delete <ref>` | Remove the clip |+| `delete <ref>` | Remove the clip, or only its `--start` to `--end` range, keeping the parts before and after || `set <ref> <field>=<value>` | Set `volume`, `rate` (playback rate) or `track` (a whole number) || `duplicate <ref>` | Copy the clip to `--at <time>` (default: right after the clip) || `apply <file>` | Apply a JSON array of edits, such as `[{"verb": "move", "ref": "#intro", "time": "+1"}]`, all or nothing. Pass `-` to read it from stdin. |@@ -1141,13 +1142,14 @@ npx hyperframes timeline delete '#outro' --jsonA time is seconds (`4.5`), an offset from the clip's start (`+1`, `-0.5`),frames (`30f`), `end`, or an anchor on another clip: `after:#intro`,-`before:#intro`, `start-of:#intro` or `end-of:#intro`.+`before:#intro`, `start-of:#intro` or `end-of:#intro`. A flag an edit command does not+use is refused before anything is written.| Flag | Applies to | Description || ------------- | -------------------------------------------------------------- | ------------------------------------------------------------- || `--plan` | `move`, `trim`, `split`, `delete`, `set`, `duplicate`, `apply` | Print the result and the diff without writing || `--overwrite` | `move`, `trim` | Allow the clip to overlap a neighbour on its track |-| `--snap` | `move`, `trim`, `split`, `duplicate` | Round times to whole frames. Needs `data-fps` on the project. |+| `--snap` | `move`, `trim`, `split`, `delete`, `duplicate` | Round times to whole frames. Needs `data-fps` on the project. || `--at` | `duplicate` | Where the copy starts || `--dir` | all edit commands | Project directory (default: current) || `--json` | all edit commands | Machine-readable result, with the receipt `undo` takes |diff --git a/packages/cli/src/commands/timeline.ts b/packages/cli/src/commands/timeline.tsindex 314d2f1bff..80bf990868 100644--- a/packages/cli/src/commands/timeline.ts+++ b/packages/cli/src/commands/timeline.ts@@ -1,4 +1,4 @@-import { defineCommand } from "citty";+import { defineCommand, type ArgDef } from "citty";import type { Example } from "./_examples.js";import { describeProject } from "../timeline/describeProject.js";import { formatTimeline } from "../timeline/formatTimeline.js";@@ -7,7 +7,7 @@ import { resolveProject } from "../utils/project.js";import { withMeta } from "../utils/updateCheck.js";import { runApply, runIds, runUndo } from "../timeline/a2Commands.js";import { runMutation } from "../timeline/a2MutationCommand.js";-import type { MutationVerb } from "../timeline/a2Shared.js";+import { FIELDS_READ_BY_VERB, type MutationVerb } from "../timeline/a2Shared.js";import { resolveExtraPositionals } from "../utils/reject-extra-positionals.js";import { assertKnownFlags } from "../utils/reject-unknown-flags.js";@@ -17,21 +17,30 @@ export const examples: Example[] = [["Delete a clip and return a receipt", "hyperframes timeline delete '#hero' --json"],];+const MUTATION_OPTIONS: Record<string, ArgDef> = {+ time: { type: "positional", required: true },+ at: { type: "string" },+ start: { type: "string" },+ end: { type: "string" },+ duration: { type: "string" },+ volume: { type: "string" },+ rate: { type: "string" },+ track: { type: "string" },+ overwrite: { type: "boolean", default: false },+};+function mutationCommand(verb: MutationVerb) {+ const fields = FIELDS_READ_BY_VERB[verb];return defineCommand({meta: { name: verb, description: `${verb} a timeline clip` },args: {ref: { type: "positional", required: true },- time: { type: "positional", required: verb === "move" || verb === "split" },- at: { type: "string" },+ ...(verb === "set" && { assignment: { type: "positional", required: false } }),+ ...Object.fromEntries(fields.map((field) => [field, MUTATION_OPTIONS[field]!])),dir: { type: "string" },- start: { type: "string" },- end: { type: "string" },- duration: { type: "string" },plan: { type: "boolean", default: false },json: { type: "boolean", default: false },- overwrite: { type: "boolean", default: false },- snap: { type: "boolean", default: false },+ ...(verb !== "set" && { snap: { type: "boolean", default: false } }),},async run({ args }) {await runMutation(verb, args);diff --git a/packages/cli/src/timeline/a2Commands.ts b/packages/cli/src/timeline/a2Commands.tsindex 118478fbaf..06e8021834 100644--- a/packages/cli/src/timeline/a2Commands.ts+++ b/packages/cli/src/timeline/a2Commands.ts@@ -18,6 +18,7 @@ import {diff,fpsFor,isRecord,+ FIELDS_READ_BY_VERB,mutationConflict,positional,publicReceipt,@@ -104,6 +105,17 @@ function preparePlanEdit(fix: "use move, trim, split, delete, set, or duplicate",};}+ const fields = FIELDS_READ_BY_VERB[edit.verb as MutationVerb];+ const unused = Object.keys(edit).find(+ (key) => key !== "verb" && key !== "ref" && !fields.includes(key),+ );+ if (unused) {+ return {+ ok: false,+ reason: `${edit.verb} does not use ${unused}`,+ fix: `remove ${unused}; ${edit.verb} takes ${fields.join(", ")}`,+ };+ }const resolved = resolveRef(timeline, edit.ref);if (!resolved.ok) return resolved;const before = sourceByFile.get(resolved.row.file);diff --git a/packages/cli/src/timeline/a2Shared.ts b/packages/cli/src/timeline/a2Shared.tsindex 44bab9d666..21e290290e 100644--- a/packages/cli/src/timeline/a2Shared.ts+++ b/packages/cli/src/timeline/a2Shared.ts@@ -4,7 +4,11 @@ import {removeElementFromHtml,splitElementInHtml,} from "@hyperframes/studio-server";-import type { AppliedFileMutation, PatchOperation } 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";@@ -17,6 +21,15 @@ 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 };@@ -196,24 +209,14 @@ function splitMutation(context: MutationContext, args: Record<string, unknown>):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 = splitElementInHtml(+ const split = splitSource(+ context,context.before,context.resolved.target,time.seconds,- nextFreeSplitId(context.before, splitBaseId(context.row)),- {- start: context.row.start,- duration: context.row.duration,- track: context.row.trackIndex,- },+ context.row.duration,);- if (!split.matched || !split.newId) {- return {- ok: false,- reason: `${context.ref} cannot be split at ${time.seconds}`,- fix: "choose a time inside the clip",- };- }+ if (!split.ok) return split;return {ok: true,after: split.html,@@ -222,6 +225,30 @@ function splitMutation(context: MutationContext, args: Record<string, unknown>):};}+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;@@ -321,15 +348,65 @@ function trimDuration(context: MutationContext, expression: string | undefined)return parseMutationTime(context, expression, "pass a valid duration");}-function deleteMutation(context: MutationContext): MutationDecision {+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(context.before, context.resolved.target),- nextStart: context.row.start,- nextDuration: context.row.duration,+ 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"@@ -403,7 +480,7 @@ export function decideMutation(case "split":return splitMutation(context, args);case "delete":- return deleteMutation(context);+ return deleteMutation(context, args);case "set":return setMutation(context, args);case "duplicate":diff --git a/packages/cli/src/timeline/timeline.e2e.test.ts b/packages/cli/src/timeline/timeline.e2e.test.tsindex feec81d936..34701fbfa3 100644--- a/packages/cli/src/timeline/timeline.e2e.test.ts+++ b/packages/cli/src/timeline/timeline.e2e.test.ts@@ -212,6 +212,80 @@ describe("timeline edit command", () => {}});+ 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 {