From b6a651f4d0672d7221a03c78aa4a039237434b49 Mon Sep 17 00:00:00 2001
From: Rene Zander <renezander030@gmail.com>
Date: Wed, 8 Jul 2026 07:24:21 +0000
Subject: [PATCH 01/17] feat(sync-timelines): reconcile drifted timeline
 mirrors from draft_content.json (#39)

On CapCut >= 8.7 the app can drive the timeline from template-2.tmp /
draft_info.json instead of draft_content.json, so a CLI edit that only the
canonical file carries is silently ignored (#35). diagnose detects the
condition but had no repair path.

capcut sync-timelines <project> compares every readable timeline target
against draft_content.json (always canonical for this command; direction is
never inferred from mtimes) and prints a plan of what drifted, including the
pre-open mirror case where draft_info.json still carries a stale draft GUID.
--apply performs the write by reusing loadDraft/saveDraft, so all targets are
rewritten transactionally inside their own envelopes with .bak backups and
the existing concurrency checks. It refuses to write while the editor is
running unless --force-write, no-ops with exit 0 when targets agree, and
reports a mirror that exists but holds no readable timeline (binary/encrypted
template-2.tmp) as unreconcilable with the fixture-bundle workaround instead
of pretending success. diagnose's next_actions now point at sync-timelines as
the remedy instead of deferring to issue #35.
---
 src/command-specs.ts         |   5 ++
 src/index.ts                 | 102 +++++++++++++++++++++++++++++++-
 src/store.ts                 | 110 ++++++++++++++++++++++++++++++++++-
 test/sync-timelines.test.mjs | Bin 0 -> 9259 bytes
 4 files changed, 214 insertions(+), 3 deletions(-)
 create mode 100644 test/sync-timelines.test.mjs

diff --git a/src/command-specs.ts b/src/command-specs.ts
index aadc1ef..e189315 100644
--- a/src/command-specs.ts
+++ b/src/command-specs.ts
@@ -178,6 +178,7 @@ const usages = {
   doctor: "capcut doctor",
   diagnose: "capcut diagnose <project> [--bundle <report.json>]",
   fixture: "capcut fixture <project> --out <dir>",
+  "sync-timelines": "capcut sync-timelines <project> [--apply]",
   restore: "capcut restore <project> [--step <number> | --list]",
   serve: "capcut serve [--queue <path>] [options]",
   decrypt: "capcut decrypt <project-or-file>",
@@ -336,6 +337,9 @@ const optionsByCommand: Record<string, OptionSpec[]> = {
   concat: [OUT],
   diagnose: [option("bundle", ["--bundle"], "path", "Write a redacted JSON diagnostic bundle.")],
   fixture: [option("out", ["--out"], "path", "Output directory for the sanitized bundle.")],
+  "sync-timelines": [
+    option("apply", ["--apply"], "boolean", "Write the reconciled timelines (default: print the plan only)."),
+  ],
   "replace-media": [
     option("retime", ["--retime"], "boolean", "Fit the segment to the new clip instead of preserving in/out."),
     option("ffprobe_cmd", ["--ffprobe-cmd"], "path", "ffprobe binary for duration/dimension detection."),
@@ -426,6 +430,7 @@ const mutating = new Set([
   "prune",
   "relink",
   "replace-media",
+  "sync-timelines",
   "concat",
   "restore",
   "export",
diff --git a/src/index.ts b/src/index.ts
index 6199323..add839b 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -89,7 +89,7 @@ import { replaceMedia } from "./replace.js";
 import { serveQueue } from "./serve.js";
 import { addSfx } from "./sfx.js";
 import { parseSrt } from "./srt.js";
-import { diagnoseDraftStore, discoverDraftStore } from "./store.js";
+import { diagnoseDraftStore, discoverDraftStore, editorProcesses, planTimelineSync } from "./store.js";
 import { formatDuration, formatTime, parseTimeInput, srtTime } from "./time.js";
 import { translateDraft } from "./translate.js";
 import { detectVersion } from "./version.js";
@@ -156,6 +156,7 @@ export const COMMANDS = [
   "doctor",
   "diagnose",
   "fixture",
+  "sync-timelines",
   "restore",
   "serve",
   "decrypt",
@@ -295,6 +296,11 @@ Maintenance & inspection:
   fixture    <project> --out <dir>              Build a shareable, redacted compatibility bundle
              (timeline JSON only, no media; home paths + emails redacted) to
              attach to a version-support issue like #35.
+  sync-timelines <project> [--apply]            Reconcile timeline mirrors (template-2.tmp,
+             draft_info.json) that drifted from draft_content.json, so a CLI
+             edit is honored by CapCut >= 8.7 (issue #35). Prints the plan by
+             default; writes only with --apply. Refuses to write while the
+             editor is running unless --force-write.
 
 Animate:
   keyframe   <project> <id> <property> <time> <value>
@@ -633,6 +639,7 @@ interface Flags {
   continueOnError?: boolean;
   check?: boolean;
   plan?: boolean;
+  apply?: boolean;
 }
 
 // Map CLI enum flags -> enums.json category key. Order matters for HELP text.
@@ -935,6 +942,8 @@ function parseFlags(args: string[]): { positional: string[]; flags: Flags } {
       flags.check = true;
     } else if (a === "--plan") {
       flags.plan = true;
+    } else if (a === "--apply") {
+      flags.apply = true;
     } else {
       const hit = ENUM_FLAG_MAP.find((f) => f.flag === a);
       if (hit) {
@@ -2356,6 +2365,88 @@ function cmdDiagnose(projectPath: string | undefined, flags: Flags): void {
   }
 }
 
+// `sync-timelines` repairs a draft whose mirror files (template-2.tmp /
+// draft_info.json — including the pre-open mirror's stale GUID) drifted from
+// draft_content.json, the CapCut >= 8.7 "CLI edit silently ignored" failure
+// (issue #35 / #39). draft_content.json is canonical; the write reuses
+// saveDraft so every readable target is rewritten transactionally inside its
+// own envelope. Plan-only by default; --apply writes.
+function cmdSyncTimelines(projectPath: string | undefined, flags: Flags): void {
+  if (!projectPath) die("Usage: capcut sync-timelines <project> [--apply] [--force-write]");
+  const plan = planTimelineSync(projectPath);
+
+  const warnUnreconcilable = (): void => {
+    if (flags.quiet) return;
+    for (const u of plan.unreconcilable) {
+      process.stderr.write(`WARNING ${u.file}: ${u.reason}. ${u.workaround}\n`);
+    }
+  };
+
+  if (plan.in_sync) {
+    const message =
+      plan.unreconcilable.length === 0
+        ? "All readable timeline targets already agree — nothing to write."
+        : `Readable timeline targets agree, but ${plan.unreconcilable.map((u) => u.file).join(", ")} cannot be reconciled by the CLI — see unreconcilable.`;
+    out({ ok: plan.unreconcilable.length === 0, applied: false, message, ...plan }, flags);
+    if (!flags.quiet) process.stderr.write(`${message}\n`);
+    warnUnreconcilable();
+    return;
+  }
+
+  if (!flags.apply) {
+    const message = `Would rewrite ${plan.drifted.join(", ")} from draft_content.json. Re-run with --apply to write.`;
+    out({ ok: true, applied: false, message, ...plan }, flags);
+    if (!flags.quiet) {
+      for (const target of plan.targets) {
+        if (target.state !== "drifted") continue;
+        const guidNote = target.guid_drifted ? ` [stale GUID ${target.guid} -> canonical]` : "";
+        process.stderr.write(`plan: rewrite ${target.file} (envelope: ${target.envelope})${guidNote}\n`);
+      }
+      warnUnreconcilable();
+      process.stderr.write("Plan only — re-run with --apply to write.\n");
+    }
+    return;
+  }
+
+  if (!flags.forceWrite) {
+    const running = editorProcesses();
+    if (running.length > 0) {
+      die(
+        `${running.join(" / ")} is running. Close the editor before repairing this draft, ` +
+          "or pass --force-write if you accept that the app may overwrite the change.",
+      );
+    }
+  }
+
+  const { draft, filePath } = loadDraft(plan.canonical_path);
+  saveDraft(filePath, draft); // no-ops under --dry-run
+
+  if (!isDryRun()) {
+    const verify = planTimelineSync(projectPath);
+    if (!verify.in_sync) {
+      die(
+        `sync-timelines wrote the targets but they still diverge (${verify.drifted.join(", ")}). ` +
+          "Restore from the .bak files and report this.",
+      );
+    }
+  }
+  out(
+    {
+      ok: true,
+      applied: !isDryRun(),
+      project_dir: plan.project_dir,
+      canonical: plan.canonical,
+      reconciled: plan.drifted,
+      backups: isDryRun() ? [] : plan.drifted.map((file) => `${file}.bak`),
+      unreconcilable: plan.unreconcilable,
+      in_sync: !isDryRun(),
+    },
+    flags,
+  );
+  if (!flags.quiet) process.stderr.write(`Reconciled from draft_content.json: ${plan.drifted.join(", ")}\n`);
+  warnUnreconcilable();
+}
+
 function cmdTemplates(flags: Flags): void {
   const cliDir = path.dirname(fileURLToPath(import.meta.url));
   const templatesPath = path.join(cliDir, "..", "templates");
@@ -2693,6 +2784,8 @@ const SUMMARIES: Record<string, string> = {
   enums: "List enum slugs (transitions, masks, effects, ...) by category.",
   doctor: "Environment preflight (Node, whisper, API key, project dir).",
   diagnose: "Inspect canonical draft files, divergence, and editor-write safety.",
+  "sync-timelines":
+    "Reconcile timeline mirrors (template-2.tmp, draft_info.json) drifted from draft_content.json (plan by default; --apply writes).",
   prune: "Remove materials no segment references.",
   relink: "Repair broken media paths (--dir or --from/--to).",
   timeline: "Show the track/segment layout (JSON, or -H ASCII bars).",
@@ -3075,6 +3168,13 @@ async function main(): Promise<void> {
     process.exit(0);
   }
 
+  // `sync-timelines` must see drifted/unreadable siblings itself — loadDraft would
+  // pick template-2.tmp as canonical on modern storage, the opposite of the repair.
+  if (cmd === "sync-timelines") {
+    cmdSyncTimelines(projectPath, flags);
+    process.exit(0);
+  }
+
   // `restore` copies a backup/snapshot back over the draft — no loadDraft/parse needed.
   if (cmd === "restore") {
     cmdRestore(projectPath, flags);
diff --git a/src/store.ts b/src/store.ts
index d93d42d..f2ac24d 100644
--- a/src/store.ts
+++ b/src/store.ts
@@ -281,14 +281,120 @@ export function isManagedDraftPath(path: string): boolean {
   return path.replace(/\\/g, "/").toLowerCase().includes("/com.lveditor.draft/");
 }
 
+// Files CapCut may read as its timeline source instead of draft_content.json:
+// template-2.tmp (>= 8.7 storage) and draft_info.json (the pre-open mirror of a
+// CLI-built draft). draft_meta_info.json without a timeline is normal
+// registration metadata, not a mirror, so it is never flagged unreconcilable.
+const MIRROR_FILES = new Set<string>(["draft_info.json", "template-2.tmp"]);
+
+export interface TimelineSyncTarget {
+  file: string;
+  state: "canonical" | "in_sync" | "drifted";
+  envelope: string;
+  timeline_hash: string | null;
+  guid: string | null;
+  guid_drifted: boolean;
+  tracks?: number;
+  segments?: number;
+}
+
+export interface TimelineSyncUnreconcilable {
+  file: string;
+  reason: string;
+  workaround: string;
+}
+
+export interface TimelineSyncPlan {
+  project_dir: string;
+  canonical: string;
+  canonical_path: string;
+  version: string | null;
+  modern_storage: boolean;
+  in_sync: boolean;
+  targets: TimelineSyncTarget[];
+  drifted: string[];
+  unreconcilable: TimelineSyncUnreconcilable[];
+}
+
+function syncTarget(candidate: DraftCandidate, state: TimelineSyncTarget["state"], guidDrifted: boolean) {
+  return {
+    file: candidate.name,
+    state,
+    envelope: candidate.envelopePath.length === 0 ? "root" : candidate.envelopePath.join("."),
+    timeline_hash: candidate.timelineHash,
+    guid: candidate.draft?.id ?? null,
+    guid_drifted: guidDrifted,
+    tracks: candidate.draft?.tracks.length,
+    segments: candidate.draft?.tracks.reduce((sum, track) => sum + track.segments.length, 0),
+  };
+}
+
+/**
+ * Plan for `sync-timelines` (issue #39, symptom #35): draft_content.json is
+ * canonical; every other readable timeline target is compared against it by
+ * timeline hash. Direction is always draft_content.json -> mirror, never
+ * inferred from mtimes (copy tools and sync clients rewrite those). A mirror
+ * file that exists but holds no readable timeline (binary/encrypted
+ * template-2.tmp) cannot be reconciled and is reported as such instead of
+ * being silently skipped.
+ */
+export function planTimelineSync(input: string): TimelineSyncPlan {
+  const store = discoverDraftStore(input);
+  const canonical = store.targets.find((candidate) => candidate.name === "draft_content.json");
+  if (!canonical?.draft) {
+    throw new Error(
+      "sync-timelines needs a readable draft_content.json (the canonical timeline source). " +
+        "Run `capcut diagnose <project>` to inspect what is on disk.",
+    );
+  }
+
+  const targets: TimelineSyncTarget[] = [syncTarget(canonical, "canonical", false)];
+  const drifted: string[] = [];
+  const unreconcilable: TimelineSyncUnreconcilable[] = [];
+  for (const candidate of store.candidates) {
+    if (!candidate.exists || candidate.path === canonical.path) continue;
+    if (!candidate.parseable || !candidate.draft) {
+      if (MIRROR_FILES.has(candidate.name)) {
+        unreconcilable.push({
+          file: candidate.name,
+          reason: candidate.error ?? "no readable timeline",
+          workaround:
+            "The CLI cannot reconcile this file. Build a redacted bundle with `capcut fixture <project> --out <dir>` " +
+            "and attach it to issue #35 so support for this storage layout can be added.",
+        });
+      }
+      continue;
+    }
+    const inSync = candidate.timelineHash === canonical.timelineHash;
+    targets.push(syncTarget(candidate, inSync ? "in_sync" : "drifted", candidate.draft.id !== canonical.draft.id));
+    if (!inSync) drifted.push(candidate.name);
+  }
+
+  return {
+    project_dir: store.projectDir,
+    canonical: canonical.name,
+    canonical_path: canonical.path,
+    version: store.version,
+    modern_storage: store.modernStorage,
+    in_sync: drifted.length === 0,
+    targets,
+    drifted,
+    unreconcilable,
+  };
+}
+
 export function diagnoseDraftStore(input: string): DraftStoreReport {
   const store = discoverDraftStore(input);
   const running = editorProcesses();
   const actions: string[] = [];
   if (store.diverged)
-    actions.push("Timeline files diverge. Close CapCut, back up the project, then run a dry-run edit before writing.");
+    actions.push(
+      "Timeline files diverge. Close CapCut, then run `capcut sync-timelines <project> --apply` to reconcile them from draft_content.json.",
+    );
   if (store.modernStorage && !store.targets.some((candidate) => candidate.name === "template-2.tmp")) {
-    actions.push("CapCut >= 8.7 detected without a readable template-2.tmp timeline; attach this report to issue #35.");
+    actions.push(
+      "CapCut >= 8.7 detected without a readable template-2.tmp timeline; run `capcut sync-timelines <project>` to see which targets can be reconciled.",
+    );
   }
   if (running.length > 0) actions.push(`Close ${running.join(" / ")} before editing this managed draft.`);
   if (actions.length === 0)
diff --git a/test/sync-timelines.test.mjs b/test/sync-timelines.test.mjs
new file mode 100644
index 0000000000000000000000000000000000000000..fb879c0d8abba015c13c37753e07b495ae664e2a
GIT binary patch
literal 9259
zcmc&)>u%h*6>j^}PeDwJt=!INoCMj+q+VbXcZ0NPT5MA64{u=85;eoMMw*J0Cx&65
z578&=lk_`>q(+>PugIbSj93zRNS@1gKAvN}T-A*g(inyRil$zQQB~(^=H5(=ZFFWw
zFZQ$>cqPnAt}AifADb<7nV+nhI#b5<$7YLVoxi`Vva!hO)#dlPRPITA(#9J1`|>=u
zYPoU`jgt9hShI9**NwI+ypGo{q6O`8mFp%RQAZ<wuJzXLSJE!}o0f%D%~<5hWQ{&k
zW1(#<&?*yYMCIDn%|G1nmFWhj=`_bNp~JdS>Ce$NSc|Vpy%{`RsB)zmGv!Z{tkmg}
z=j=_V;=@9TOjdQJGg%6&m#Wm2nu+y7T4C|=)!R2>-PBeITZ_EG8BVggvZ}IJxUNK^
zjcJwm?X%}Ik|%{#pD?qL*}0H;u5!W0W?6Ez5~Va&EOpah>p8z=q5J7x(N>w&5ZUeL
zh?YzC#nqk=jk0Z1@vlPYd?rToR_Bv$>}ZTZLR4~z-H%9fDxaKP(sBK#ylo`OpNS_Y
z2L}iA<K`4AGZWAJ0|Z`3LuV}Xd?v2MTIY6wIR{@KjKxCf`NHDqo2PhUd06e6*^@6v
z;@U}DmC_b<v!uB=@QJD0CZj!N*=WpfE?^Aa$LQ<ytMmYGYiwY&)>U4wO(%$Th!4kC
z?z|tKV5GfVkt|X&p8RS3leCDbv({n&HfPj)2`iC+kK+2H+uTyZ1+^^kmXu2WE_AMF
z{bN5w2-)U3enSgHL(EF4JbDu(pU6t%cbqT!%rZ|33Fq%Gg)>%0Z;fU}UccD8-U}XT
ztSpuHni)IIs!<a%a_6!lsp_8Z?Tfa`RRe#_by27Wnjm59YvT1k-yDhm{`)`9!R6{z
zYXu3cSE}->zzL1&`6TaP$R9<TrkxY|0f_9*L7l5lc>cy>X9_N&$T|5GWLSzA){W?n
ze$?m!*r`9k^<h-rd>nn+Y@%gaskLfeKnY9oK{a`r0<}a!NL$S(bo{@(|NA?kstZ-(
zsQW@zxfiOdqW1CJ)V1x6F;<tQSk$EpR{r0kL{B|A?Nk9^d8<BT5krV|g3UwG!{UUH
zGI4;K?2i!`a+S4qVgTop(f<AmIA(;)ZUW?B?5++*5JBfk-8pq}ne5u5YRhsgp57rm
z*4%*LtJns!?S=bZvJXHI_gmK;s<Xks!hOM8QUfrOqLB?tC98Hd6R^SIx5DMQgg;#Y
zL$empa{*tnO^XBsCnRX12XT!JbIgVOl#JLSAtx9(sS`@bp=~mPmjVBCRmirq`;bl<
z-*`-CfAGO%0HStLBg)9GaK=cKKnf>EDc~mCenh?iK%&H%6sbQPdq|iCKYGc*gxUQZ
z@0_Mco!jhMcGTKp^7SZ^MHaY+umN*zr16H`fynPeI!=yvwaJ_N=y%{~QL6sc$}(x-
z%+j`IOhA5WERd|3iQiq(d;0zQba)nJ<P=G#)GCK{f%EE?fx0>&3*SAki>Dg`&|8VA
zUYaYl`m;X;@5kFTHSi9K_hTQ#8-It`EdvFuI7QM(GA|=kYGpH5)}#gUWs<=0;O7=k
z$PkBzhXEos(uXv_UrEOZ0&It!HTXhg2_8sH<HV05q^8gr5jomQ8oxJ!1Jxy%WecZ1
zQ=%y4e6I2>@yL<cf(=au9gFE?LWaAX4sG`_j*X3m(7<jvR(VGi;GN-hYeU}idNer>
zp<BEj`L2tc+t#|q**tdm(-I`rRR-G);|AXwb}@fUn#aZB0$9@Jsu-XGK0E|f9vZti
zt3SsmIBeuRpC^pT-v*t+g+mv`yW@63vD0?`;AmvsfI`H9D$Wt@2HAi-pJ_%!F+fHT
zB_V^rOAN@S0BNDu9jb`B0@Wg*ci|og3PPR}`${%OC69>#uQn&PyL3ci!(wUVWkdQ7
z^HXBoFnxT-xOIjjcWJ4rxm}FK6ATXe+zKlsW6!R{ckhlIkZi0bl2<pgRa~JqI;4QS
zul}~SK=dQzv!PQlBx>ZBog0`KIrwv$iczq42wWs%`|}3CnFkSxm%B;ju@+(H&BYWx
zsmcOwN&GdFO`|==Z2XQa=#&<P?Y*2Xau<%oNN+bfN!amA(ES#nQx~iZ$|N9A5@gwF
z&j>DMMBA&+?;Qo{nLO`rDAiR~wxD*&X#4KrNHJKJ%ip&yvgIldUZs}-sv7q##|-JH
zRvhqsL^6ei7Etk#bA>_#?qm`s^l4wnd85>4A&`;L?<8sw*l+k*2xW&c_o94}q=-9x
z2KHB<JBBh8xt>5hoFML|mOx*a;dxtu#K@9h`qCL`i^_y4j=~NP?)gVx2$M<PTuz#{
zqMU!B)%usbO>B4!@y*9@A&=~ja|iYef81YyQb6(#ZS^_)<1w1qVu``3L!`9l2H{qT
zt7cn~MdTTX{uT?7hCf2-pprZQRKsF0!7JPbSs^E?XxfY`$^DybU>y%3ij-%;h5m+m
zHfoYohV@X@U~8Z@J^_O0oast7ms3?`&E*Oel1<qObyZ{{V&hcGTAtxs$VLOzk6SLX
zzxp+VOehe4LkYA;0+{qa_6|yuH!v4nL;a_lZ=yVap@D3+F-ydNNQn^y-!$v^;3Hq}
z5FN4IxA=ksnA@bR>*icGHA;hkA758X|A5-{)Wmq%6V<`hkKg_9?#;W`J>UC@3T%XO
zJ)QqwGQcfFf9Ssb5t^*4@{)bEi>Zy%IwG=jWewSBz_1T9Q7B`;2)8J8$3Jey<88OV
z`Fwc?zxCq-k1irZh?WW!*0!>Bn=Rad13~+MIBwKZ>WYvf_Tw<y-G1uxLoT(TN?M_V
zbBX&5+8iiZ31ltPXXSDZamXxpl8wRZB+uT2WbCodIBp0V=$3oo&R8N1d<5vn1MMbg
z!(lt1Moq(^GBtOMC{SC)nL#%rF5^O|x1kM7@VLiv+&U_EWT6NAsEX7Lay{|CU9wG=
z$R%1&WE-mdL!|Fvxqi$3AVWkk5ZZrWEjrX6A5l^D8X3TISC-tO(+?^9J^*sC)}TLa
z$`f=U?S<P8Q;YQf6W?}r?A55EHMn90-nK^X)@4JwX4MT@4DsNj2?ZY-$_40&D@Toe
zOUj&U)USQhHwBz?JI&Sh&?9^Hl>2!ou1l(3_G;31XL981@8!8dS19bn?QMoP)JG<|
zaB51_G)}p<mJ5I1HVbs-M7u%>L!9E)GLfI)bM<n0c-oKe0>Y2(^f4O6ZJ)Xc{f=(y
z`1Fz?f}12>9-`9iBZOGL=benEfV3&^8ct7BAi*27>ysz`Ju1reSI?h^&s=!tE_*<w
z&A{W)mj@%H3UuZz8iMFL>Uo8(6&jSmUAQj4X$p`Fv9R<Um+oZr{>|&ZzIppL>{^Jf
zgr9f`=<9MPo>ztDXf+Uq+qx9aQ$0{H4f|2z_6Q8uxFiC!z31S<NKDaLj^2|7gtK?w
zW;tjg^}L~gBY<{V)oYySkK#Esh}~k&l@m9&YsV-1p3bmq9*8f#=nME0`ut9?>tAzt
zt!bxd(+LOxdZ`5Wc~h4c=*6LkZIu0h;t%>H;WbJ{2M6JPe%%jI+|qB{&bQPx81Zqt
zauNRp1u3INBM-ovgA-@0A+k;%OgN15;12jpf*V^GSmgHdrxVp>tYMVt2KhSp1}3)d
zk96ejuRHFjO$VJt{E|;8?pISBK;}Rx_EQwUyewA&bId99c*7?KMEp@jmp47k@%LEi
w41*8VIjg@9po1XqM0Ylb`$^r$o2mQ*ieX%-Bks{JJh8TRN`)N$6vOoMKNG6XY5)KL

literal 0
HcmV?d00001


From 97f74c564d9224cf1913a2ad543de59933787c04 Mon Sep 17 00:00:00 2001
From: Rene Zander <renezander030@gmail.com>
Date: Wed, 8 Jul 2026 07:25:38 +0000
Subject: [PATCH 02/17] feat(lint): fix line-too-long + caption-gap-too-small;
 new unknown-effect-slug rule
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Follow-up to #42. Extends FIXABLE_CODES with two mechanically-safe
repairs and adds one report-only rule.

line-too-long (fix pass 4): greedy word wrap that only swaps spaces for
newlines 1:1, so text length — and therefore the UTF-16LE byte offsets
in the content styles[] ranges — never shifts. Existing line breaks are
kept; lines already within the limit are untouched; words longer than
maxCharsPerLine are never split mid-word and stay reported.

caption-gap-too-small (fix pass 3): pulls the earlier caption's end
back until the gap reaches minGapBetweenCaptionsUs — the same mutation
direction as the existing overlap fix (pass 2), so it can never move a
segment start, create a new overlap, or go negative. When the shrink
would zero out the caption it is skipped and stays reported.

missing-material and missing-file stay report-only, deliberately:
- missing-material: a segment whose material_id resolves nowhere is
  dangling timeline content. The only mechanical "fix" is deleting the
  segment, i.e. auto-deleting user content; the right repair is usually
  re-adding the material. `prune` is the inverse direction (materials no
  segment references) and does not apply.
- missing-file: paths are host-dependent (the test fixture itself ships
  Windows C:\ paths) and the file may exist on the machine the draft is
  destined for. Deleting the material would destroy content over an
  environment difference; `relink`/`replace` are the intended repairs.

unknown-effect-slug (report-only, warning): validates effect_id /
resource_id on materials.video_effects entries (add-effect, add-filter)
and materials.material_animations animations (text-anim, image-anim)
against the bundled enum table — enums.json across both namespaces plus
the inline knossos-verified starter catalogues, now exposed via
effectCatalogue()/imageAnimCatalogue(). Ecosystem tools apply stale
effect ids that CapCut silently ignores (GuanYixuan/pyCapCut#12); lint
now surfaces them before the app eats them. Not fixable: a repair would
mean guessing which resource the author meant. Warning severity keeps
the 0/1/2 CI exit-code contract intact.

Tests: 220 -> 224 (fix round-trips for both new fixable codes; bogus and
known-id cases for unknown-effect-slug).
---
 src/decorators.ts  |  18 ++++
 src/factory.ts     |  18 ++++
 src/lint.ts        | 161 +++++++++++++++++++++++++++++++-
 test/lint.test.mjs | 225 +++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 421 insertions(+), 1 deletion(-)

diff --git a/src/decorators.ts b/src/decorators.ts
index f634d0f..1967ccf 100644
--- a/src/decorators.ts
+++ b/src/decorators.ts
@@ -558,6 +558,24 @@ export function imageAnimSlugs(): string[] {
   return Object.keys(IMAGE_ANIMS);
 }
 
+// Exposed so lint's unknown-effect-slug check recognises the inline starter
+// catalogue: these effect_ids are knossos-verified but absent from enums.json.
+export function imageAnimCatalogue(): Array<{
+  slug: string;
+  member: string;
+  name: string;
+  effect_id: string;
+  resource_id: string;
+}> {
+  return Object.entries(IMAGE_ANIMS).map(([slug, meta]) => ({
+    slug,
+    member: meta.name,
+    name: meta.name,
+    effect_id: meta.effect_id,
+    resource_id: meta.resource_id,
+  }));
+}
+
 export interface ImageAnimOptions {
   intro?: string;
   outro?: string;
diff --git a/src/factory.ts b/src/factory.ts
index 35f5b00..53f046b 100644
--- a/src/factory.ts
+++ b/src/factory.ts
@@ -1148,6 +1148,24 @@ export function effectSlugs(): string[] {
   return Object.keys(VIDEO_EFFECTS);
 }
 
+// Exposed so lint's unknown-effect-slug check recognises the inline starter
+// catalogue: these effect_ids are knossos-verified but absent from enums.json.
+export function effectCatalogue(): Array<{
+  slug: string;
+  member: string;
+  name: string;
+  effect_id: string;
+  resource_id: string;
+}> {
+  return Object.entries(VIDEO_EFFECTS).map(([slug, meta]) => ({
+    slug,
+    member: meta.name,
+    name: meta.name,
+    effect_id: meta.effect_id,
+    resource_id: meta.resource_id,
+  }));
+}
+
 export interface AddEffectOptions {
   slug: string;
   start: number;
diff --git a/src/lint.ts b/src/lint.ts
index d3d8592..ada1563 100644
--- a/src/lint.ts
+++ b/src/lint.ts
@@ -1,6 +1,9 @@
 import { existsSync, statSync } from "node:fs";
+import { imageAnimCatalogue } from "./decorators.js";
 import type { Draft, Segment, Track } from "./draft.js";
 import { extractText, findMaterial, getTracksByType } from "./draft.js";
+import { type Category, listEnum, type Namespace } from "./enums.js";
+import { effectCatalogue, filterCatalogue } from "./factory.js";
 
 export type Severity = "error" | "warning" | "info";
 
@@ -19,7 +22,12 @@ export interface LintIssue {
 
 // Codes that lintDraft can mechanically repair via fixDraft. Any issue whose
 // code appears here is emitted with fixable:true.
-const FIXABLE_CODES = new Set<string>(["cue-too-long", "caption-overlap"]);
+//
+// Deliberately NOT here: missing-material and missing-file (the only safe
+// repair would delete user timeline content or guess a path — report-only;
+// `relink` and `replace` are the intended repairs), and unknown-effect-slug
+// (repair would mean guessing which resource the author meant).
+const FIXABLE_CODES = new Set<string>(["cue-too-long", "caption-overlap", "caption-gap-too-small", "line-too-long"]);
 
 export interface LintOptions {
   maxCharsPerLine: number;
@@ -126,9 +134,86 @@ export function lintDraft(draft: Draft, opts: LintOptions = DEFAULT_LINT_OPTIONS
     }
   }
 
+  // Effect/filter/animation resource ids the bundled enum table doesn't know.
+  // CapCut silently drops unknown resource ids (GuanYixuan/pyCapCut#12), so
+  // surface them before the app eats them. Report-only: a repair would mean
+  // guessing which resource the author meant.
+  const known = knownEffectIds();
+  const pushUnknown = (kind: string, name: string, badId: string, materialId: string) => {
+    issues.push({
+      severity: "warning",
+      code: "unknown-effect-slug",
+      message: `${kind} "${name}" (material ${shortId(materialId)}) uses effect_id ${badId} not in the bundled enum table — CapCut may silently ignore it`,
+      fixable: FIXABLE_CODES.has("unknown-effect-slug"),
+      location: { material_id: materialId },
+    });
+  };
+  for (const mat of draft.materials.video_effects ?? []) {
+    const m = mat as { id?: string; name?: string; type?: string; effect_id?: string; resource_id?: string };
+    const effectId = typeof m.effect_id === "string" ? m.effect_id : "";
+    const resourceId = typeof m.resource_id === "string" ? m.resource_id : "";
+    if (!effectId && !resourceId) continue;
+    if (known.has(effectId) || known.has(resourceId)) continue;
+    pushUnknown(m.type ?? "effect", m.name ?? "?", effectId || resourceId, m.id ?? "");
+  }
+  for (const mat of draft.materials.material_animations ?? []) {
+    const container = mat as { id?: string; animations?: Array<Record<string, unknown>> };
+    for (const anim of container.animations ?? []) {
+      const a = anim as { id?: string; name?: string; type?: string; resource_id?: string };
+      const effectId = typeof a.id === "string" ? a.id : "";
+      const resourceId = typeof a.resource_id === "string" ? a.resource_id : "";
+      if (!effectId && !resourceId) continue;
+      if (known.has(effectId) || known.has(resourceId)) continue;
+      pushUnknown(`${a.type ?? "?"} animation`, a.name ?? "?", effectId || resourceId, container.id ?? "");
+    }
+  }
+
   return issues;
 }
 
+// Every effect_id/resource_id the CLI could have written into a draft: the
+// bundled enums.json (both namespaces, all categories) plus the inline
+// knossos-verified starter catalogues that enums.json doesn't carry.
+const ENUM_CATEGORIES: Category[] = [
+  "transitions",
+  "masks",
+  "image_intros",
+  "image_outros",
+  "image_combos",
+  "text_intros",
+  "text_outros",
+  "text_loop_anims",
+  "scene_effects",
+  "character_effects",
+  "audio_effects",
+  "fonts",
+  "filters",
+];
+
+let knownIdCache: Set<string> | null = null;
+
+function knownEffectIds(): Set<string> {
+  if (knownIdCache) return knownIdCache;
+  const ids = new Set<string>();
+  const add = (id?: string) => {
+    if (id) ids.add(id);
+  };
+  for (const namespace of ["capcut", "jianying"] as Namespace[]) {
+    for (const category of ENUM_CATEGORIES) {
+      for (const e of listEnum(category, namespace)) {
+        add(e.effect_id);
+        add(e.resource_id);
+      }
+    }
+  }
+  for (const e of [...effectCatalogue(), ...filterCatalogue(), ...imageAnimCatalogue()]) {
+    add(e.effect_id);
+    add(e.resource_id);
+  }
+  knownIdCache = ids;
+  return ids;
+}
+
 export function summarize(issues: LintIssue[]): { errors: number; warnings: number; info: number; total: number } {
   let errors = 0;
   let warnings = 0;
@@ -193,6 +278,52 @@ export function fixDraft(draft: Draft, opts: LintOptions = DEFAULT_LINT_OPTIONS)
     }
   }
 
+  // Pass 3: widen under-min gaps by pulling the earlier caption's end back —
+  // the same mutation direction as pass 2, so it can never create a new
+  // overlap or move a start. Skipped when the shrink would erase the caption.
+  if (opts.minGapBetweenCaptionsUs > 0) {
+    for (const track of getTracksByType(draft, "text")) {
+      const segs = [...track.segments].sort((a, b) => a.target_timerange.start - b.target_timerange.start);
+      for (let i = 0; i < segs.length - 1; i++) {
+        const s = segs[i];
+        const next = segs[i + 1];
+        const end = s.target_timerange.start + s.target_timerange.duration;
+        const gap = next.target_timerange.start - end;
+        if (gap > 0 && gap < opts.minGapBetweenCaptionsUs) {
+          const newDuration = s.target_timerange.duration - (opts.minGapBetweenCaptionsUs - gap);
+          if (newDuration <= 0) continue;
+          const oldDuration = s.target_timerange.duration;
+          s.target_timerange.duration = newDuration;
+          if (s.source_timerange && s.source_timerange.duration === oldDuration) {
+            s.source_timerange.duration = newDuration;
+          }
+        }
+      }
+    }
+  }
+
+  // Pass 4: re-wrap over-long caption lines at word boundaries. Each break
+  // swaps one space for one newline — string length never changes, so the
+  // UTF-16LE byte offsets in the content's styles[] ranges stay valid. Words
+  // longer than the limit are never split and stay reported.
+  for (const track of getTracksByType(draft, "text")) {
+    for (const s of track.segments) {
+      const mat = findMaterial(draft.materials.texts, s.material_id);
+      if (!mat) continue;
+      let parsed: { text?: unknown };
+      try {
+        parsed = JSON.parse(mat.content);
+      } catch {
+        continue;
+      }
+      if (typeof parsed.text !== "string") continue;
+      const wrapped = rewrapText(parsed.text, opts.maxCharsPerLine);
+      if (wrapped === parsed.text) continue;
+      parsed.text = wrapped;
+      mat.content = JSON.stringify(parsed);
+    }
+  }
+
   const after = lintDraft(draft, opts);
   const remaining: LintIssue[] = [];
   const afterKeys = new Set(after.map(issueKey));
@@ -203,6 +334,34 @@ export function fixDraft(draft: Draft, opts: LintOptions = DEFAULT_LINT_OPTIONS)
   return { fixed, remaining };
 }
 
+// Re-wrap only lines that exceed maxChars; existing line breaks are kept.
+function rewrapText(text: string, maxChars: number): string {
+  return text
+    .split(/(\r?\n)/)
+    .map((part, i) => (i % 2 === 0 && part.length > maxChars ? wrapLine(part, maxChars) : part))
+    .join("");
+}
+
+// Greedy word wrap that only swaps spaces for newlines (1:1, length-neutral).
+// A multi-space separator keeps its extra spaces at the end of the broken line.
+function wrapLine(line: string, maxChars: number): string {
+  const tokens = line.split(/( +)/); // words at even indices, space runs at odd
+  let out = tokens[0] ?? "";
+  let lineLen = out.length;
+  for (let i = 1; i < tokens.length; i += 2) {
+    const sep = tokens[i];
+    const word = tokens[i + 1] ?? "";
+    if (lineLen > 0 && lineLen + sep.length + word.length > maxChars) {
+      out += `${sep.slice(0, -1)}\n${word}`;
+      lineLen = word.length;
+    } else {
+      out += sep + word;
+      lineLen += sep.length + word.length;
+    }
+  }
+  return out;
+}
+
 function issueKey(i: LintIssue): string {
   return `${i.code}|${i.location?.segment_id ?? ""}|${i.location?.material_id ?? ""}|${i.location?.path ?? ""}`;
 }
diff --git a/test/lint.test.mjs b/test/lint.test.mjs
index 485a9f8..7207e26 100644
--- a/test/lint.test.mjs
+++ b/test/lint.test.mjs
@@ -252,4 +252,229 @@ describe("capcut lint", () => {
       assert.ok(tooLong.length > 0, `expected line-too-long warning; got: ${JSON.stringify(r.json.issues)}`);
     });
   });
+
+  describe("--fix re-wraps over-long caption lines", () => {
+    const fix = tmpDraft();
+    after(() => fix.cleanup());
+
+    it("wraps at word boundaries, keeps text length, and re-lints clean", () => {
+      const draft = JSON.parse(readFileSync(fix.path, "utf-8"));
+      const longText = "the quick brown fox jumps over the lazy dog and keeps running far beyond the fence"; // 83 chars > 42
+      const mat = {
+        id: "wrap-text-mat",
+        type: "text",
+        content: JSON.stringify({ text: longText, styles: [] }),
+        font_size: 15,
+        text_color: "#FFFFFF",
+        alignment: 1,
+      };
+      draft.materials.texts = [...(draft.materials.texts ?? []), mat];
+      let textTrack = draft.tracks.find((t) => t.type === "text");
+      if (!textTrack) {
+        textTrack = { id: "wrap-text-track", type: "text", name: "captions", attribute: 0, segments: [] };
+        draft.tracks.push(textTrack);
+      }
+      textTrack.segments.push({
+        id: "wrap-seg-1-aaaa-bbbb-cccc-dddddddddddd",
+        material_id: mat.id,
+        target_timerange: { start: 300_000_000, duration: 2_000_000 },
+        source_timerange: { start: 0, duration: 2_000_000 },
+        speed: 1,
+        volume: 1,
+        visible: true,
+        clip: { alpha: 1, rotation: 0, scale: { x: 1, y: 1 }, transform: { x: 0, y: 0 } },
+        extra_material_refs: [],
+        render_index: 0,
+      });
+      writeFileSync(fix.path, JSON.stringify(draft));
+
+      const detect = spawnCli(["lint", fix.path, "--no-check-paths"]);
+      const found = detect.json.issues.filter((i) => i.code === "line-too-long");
+      assert.ok(found.length > 0, `expected line-too-long; got: ${JSON.stringify(detect.json.issues)}`);
+      assert.equal(found[0].fixable, true);
+
+      const r = spawnCli(["lint", fix.path, "--fix", "--no-check-paths"]);
+      const wrapped = r.json.fixed.filter((i) => i.code === "line-too-long");
+      assert.ok(wrapped.length > 0, `expected line-too-long in fixed; got: ${JSON.stringify(r.json.fixed)}`);
+
+      const relint = spawnCli(["lint", fix.path, "--no-check-paths"]);
+      assert.ok(
+        !relint.json.issues.some((i) => i.code === "line-too-long"),
+        `re-lint should be clean; got: ${JSON.stringify(relint.json.issues)}`,
+      );
+
+      // Word-boundary wrap must be length-neutral (spaces become newlines 1:1)
+      // so the styles[] UTF-16LE byte ranges stay valid.
+      const repaired = JSON.parse(readFileSync(fix.path, "utf-8"));
+      const content = JSON.parse(repaired.materials.texts.find((m) => m.id === "wrap-text-mat").content);
+      assert.equal(content.text.length, longText.length, "wrap must not change text length");
+      assert.equal(content.text.replace(/\n/g, " "), longText, "only spaces may become newlines");
+      for (const line of content.text.split("\n")) {
+        assert.ok(line.length <= 42, `wrapped line still too long: "${line}"`);
+      }
+    });
+  });
+
+  describe("--fix restores minimum caption gaps", () => {
+    const fix = tmpDraft();
+    after(() => fix.cleanup());
+
+    it("shrinks the earlier caption's end under --min-gap-ms and re-lints clean", () => {
+      const draft = JSON.parse(readFileSync(fix.path, "utf-8"));
+      let mat = draft.materials.texts?.[0];
+      if (!mat) {
+        mat = {
+          id: "gap-mat-1",
+          type: "text",
+          content: '{"text":"Hello","styles":[]}',
+          font_size: 15,
+          text_color: "#FFFFFF",
+          alignment: 1,
+        };
+        draft.materials.texts = [...(draft.materials.texts ?? []), mat];
+      }
+      let textTrack = draft.tracks.find((t) => t.type === "text");
+      if (!textTrack) {
+        textTrack = { id: "gap-text-track", type: "text", name: "captions", attribute: 0, segments: [] };
+        draft.tracks.push(textTrack);
+      }
+      const base = {
+        material_id: mat.id,
+        source_timerange: { start: 0, duration: 2_000_000 },
+        speed: 1,
+        volume: 1,
+        visible: true,
+        clip: { alpha: 1, rotation: 0, scale: { x: 1, y: 1 }, transform: { x: 0, y: 0 } },
+        extra_material_refs: [],
+        render_index: 0,
+      };
+      // Gap: seg A ends at 402.0s, seg B starts at 402.1s — 100ms < 200ms minimum.
+      textTrack.segments.push({
+        ...base,
+        id: "gap-seg-1-aaaa-bbbb-cccc-dddddddddddd",
+        target_timerange: { start: 400_000_000, duration: 2_000_000 },
+      });
+      textTrack.segments.push({
+        ...base,
+        id: "gap-seg-2-aaaa-bbbb-cccc-dddddddddddd",
+        target_timerange: { start: 402_100_000, duration: 2_000_000 },
+      });
+      writeFileSync(fix.path, JSON.stringify(draft));
+
+      const detect = spawnCli(["lint", fix.path, "--min-gap-ms", "200", "--no-check-paths"]);
+      const found = detect.json.issues.filter((i) => i.code === "caption-gap-too-small");
+      assert.ok(found.length > 0, `expected caption-gap-too-small; got: ${JSON.stringify(detect.json.issues)}`);
+      assert.equal(found[0].fixable, true);
+
+      const r = spawnCli(["lint", fix.path, "--fix", "--min-gap-ms", "200", "--no-check-paths"]);
+      const gapFixed = r.json.fixed.filter((i) => i.code === "caption-gap-too-small");
+      assert.ok(gapFixed.length > 0, `expected caption-gap-too-small in fixed; got: ${JSON.stringify(r.json.fixed)}`);
+
+      const relint = spawnCli(["lint", fix.path, "--min-gap-ms", "200", "--no-check-paths"]);
+      assert.ok(
+        !relint.json.issues.some((i) => i.code === "caption-gap-too-small"),
+        `re-lint should be clean; got: ${JSON.stringify(relint.json.issues)}`,
+      );
+
+      // The earlier caption's end moved back; the later caption never moves.
+      const repaired = JSON.parse(readFileSync(fix.path, "utf-8"));
+      const track = repaired.tracks.find((t) => t.segments.some((s) => s.id.startsWith("gap-seg-1")));
+      const segA = track.segments.find((s) => s.id.startsWith("gap-seg-1"));
+      const segB = track.segments.find((s) => s.id.startsWith("gap-seg-2"));
+      assert.equal(segA.target_timerange.duration, 1_900_000);
+      assert.equal(segB.target_timerange.start, 402_100_000);
+    });
+  });
+
+  describe("unknown-effect-slug detection", () => {
+    function baseEffectMaterial(id, name, effectId, resourceId) {
+      return {
+        id,
+        name,
+        type: "video_effect",
+        effect_id: effectId,
+        resource_id: resourceId,
+        adjust_params: [],
+        apply_target_type: 2,
+        category_id: "",
+        category_name: "",
+        platform: "all",
+        value: 1.0,
+      };
+    }
+
+    describe("flags ids missing from the enum table", () => {
+      const fix = tmpDraft();
+      after(() => fix.cleanup());
+
+      it("warns on bogus effect and animation ids as report-only", () => {
+        const draft = JSON.parse(readFileSync(fix.path, "utf-8"));
+        draft.materials.video_effects = [
+          baseEffectMaterial("bogus-effect-mat", "Stale Effect", "1111111111111111111", "1111111111111111111"),
+        ];
+        draft.materials.material_animations = [
+          {
+            id: "bogus-anim-container",
+            type: "sticker_animation",
+            multi_language_current: "none",
+            animations: [
+              {
+                id: "2222222222222222222",
+                resource_id: "2222222222222222222",
+                name: "Stale Anim",
+                type: "in",
+                duration: 500_000,
+                start: 0,
+                material_type: "text",
+              },
+            ],
+          },
+        ];
+        writeFileSync(fix.path, JSON.stringify(draft));
+
+        const r = spawnCli(["lint", fix.path, "--no-check-paths"]);
+        const unknown = r.json.issues.filter((i) => i.code === "unknown-effect-slug");
+        assert.equal(unknown.length, 2, `expected 2 unknown-effect-slug issues; got: ${JSON.stringify(r.json.issues)}`);
+        const materialIds = unknown.map((i) => i.location.material_id).sort();
+        assert.deepEqual(materialIds, ["bogus-anim-container", "bogus-effect-mat"]);
+        for (const i of unknown) {
+          assert.equal(i.severity, "warning");
+          assert.equal(i.fixable, false);
+        }
+        // Warnings-only draft → exit 1 per the CI contract.
+        assert.equal(r.json.summary.errors, 0);
+        assert.equal(r.status, 1);
+
+        // Report-only: --fix must not claim it repaired anything here.
+        const fixRun = spawnCli(["lint", fix.path, "--fix", "--no-check-paths"]);
+        assert.ok(
+          !fixRun.json.fixed.some((i) => i.code === "unknown-effect-slug"),
+          `unknown-effect-slug must never appear in fixed[]; got: ${JSON.stringify(fixRun.json.fixed)}`,
+        );
+        assert.ok(fixRun.json.issues.some((i) => i.code === "unknown-effect-slug"));
+      });
+    });
+
+    describe("passes on known ids", () => {
+      const fix = tmpDraft();
+      after(() => fix.cleanup());
+
+      it("accepts enum-table ids and the inline starter catalogue", () => {
+        const draft = JSON.parse(readFileSync(fix.path, "utf-8"));
+        draft.materials.video_effects = [
+          // From enums.json (capcut scene_effects: blur).
+          baseEffectMaterial("enum-effect-mat", "Blur", "15206412", "6739752823140913675"),
+          // From the inline knossos-verified starter catalogue (add-effect shake).
+          baseEffectMaterial("inline-effect-mat", "Shake", "7061205058364788270", "7061205058364788270"),
+        ];
+        writeFileSync(fix.path, JSON.stringify(draft));
+
+        const r = spawnCli(["lint", fix.path, "--no-check-paths"]);
+        assert.ok(
+          !r.json.issues.some((i) => i.code === "unknown-effect-slug"),
+          `expected no unknown-effect-slug; got: ${JSON.stringify(r.json.issues)}`,
+        );
+      });
+    });
+  });
 });

From c1a1731093390e3761c4a9aaad75a98fa3189ed8 Mon Sep 17 00:00:00 2001
From: Rene Zander <renezander030@gmail.com>
Date: Wed, 8 Jul 2026 07:39:38 +0000
Subject: [PATCH 03/17] feat(export-srt): word-level caption export with
 karaoke SRT/VTT

export-srt gains --granularity <line|word> (default line; existing
phrase-level SRT output stays byte-identical) and --format <srt|vtt>
(default srt).

Word timings are exported directly where the draft actually stores
them: caption --karaoke writes one full-phrase segment per word,
word-timed, with that word's style range highlighted. A run of such
segments is collapsed back into a single word-timed cue. Plain phrase
captions (import-srt, add-text) store no per-word timing, so timings
are interpolated within each cue, weighted by word character length;
the help text states this rather than implying stored precision.

SRT word granularity emits one cue per word. WebVTT word granularity
emits one cue per phrase with inline <00:00:01.400> word timestamps,
the karaoke form players understand. Line-granularity SRT still
round-trips through parseSrt.

Cross-repo demand: hyperaudio/hyperaudio-lite-editor#387 (word-level
VTT for karaoke burn-in), dudarenok-maker/Castwright#975 (word/
sentence/line granularity SRT+VTT export).
---
 src/command-specs.ts     |   9 ++-
 src/draft.ts             |  18 +++++
 src/index.ts             |  66 +++++++++++++++---
 src/srt.ts               | 122 ++++++++++++++++++++++++++++++++-
 src/time.ts              |   5 ++
 test/export-srt.test.mjs | 142 +++++++++++++++++++++++++++++++++++++++
 6 files changed, 348 insertions(+), 14 deletions(-)
 create mode 100644 test/export-srt.test.mjs

diff --git a/src/command-specs.ts b/src/command-specs.ts
index aadc1ef..f1edde7 100644
--- a/src/command-specs.ts
+++ b/src/command-specs.ts
@@ -132,7 +132,7 @@ const usages = {
   volume: "capcut volume <project> <id> <level>",
   trim: "capcut trim <project> <id> <start> <duration>",
   opacity: "capcut opacity <project> <id> <alpha>",
-  "export-srt": "capcut export-srt <project>",
+  "export-srt": "capcut export-srt <project> [options]",
   materials: "capcut materials <project> [--type <type>]",
   segment: "capcut segment <project> <id>",
   material: "capcut material <project> <id>",
@@ -278,6 +278,13 @@ const optionsByCommand: Record<string, OptionSpec[]> = {
       "Commit only successful operations and exit 1 if any fail.",
     ),
   ],
+  "export-srt": [
+    option("granularity", ["--granularity"], "enum", "Cue granularity: one cue per caption or per word.", {
+      values: ["line", "word"],
+      default: "line",
+    }),
+    option("format", ["--format"], "enum", "Subtitle output format.", { values: ["srt", "vtt"], default: "srt" }),
+  ],
   "import-srt": [
     TRACK_NAME,
     STYLE_REF,
diff --git a/src/draft.ts b/src/draft.ts
index e241764..390d5d1 100644
--- a/src/draft.ts
+++ b/src/draft.ts
@@ -323,6 +323,24 @@ export function extractText(content: string): string {
   return content;
 }
 
+// Style `range` entries are UTF-16LE byte offsets (see setTextRanges).
+export function extractStyleRanges(content: string): Array<[number, number]> {
+  try {
+    const parsed = JSON.parse(content) as { styles?: Array<{ range?: unknown }> };
+    if (!Array.isArray(parsed.styles)) return [];
+    const ranges: Array<[number, number]> = [];
+    for (const style of parsed.styles) {
+      const r = style.range;
+      if (Array.isArray(r) && r.length === 2 && typeof r[0] === "number" && typeof r[1] === "number") {
+        ranges.push([r[0], r[1]]);
+      }
+    }
+    return ranges;
+  } catch {
+    return [];
+  }
+}
+
 export function updateTextContent(content: string, newText: string): string {
   try {
     const parsed = JSON.parse(content);
diff --git a/src/index.ts b/src/index.ts
index 6199323..810228d 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -39,6 +39,7 @@ import { detectEncryption } from "./decrypt.js";
 import { type DoctorCheck, draftDirs, runDoctor } from "./doctor.js";
 import type { Draft, Segment, Track } from "./draft.js";
 import {
+  extractStyleRanges,
   extractText,
   findDraft,
   findMaterial,
@@ -88,9 +89,9 @@ import { buildRenderPlan, renderDraft } from "./render.js";
 import { replaceMedia } from "./replace.js";
 import { serveQueue } from "./serve.js";
 import { addSfx } from "./sfx.js";
-import { parseSrt } from "./srt.js";
+import { collapseKaraokeRuns, cueWords, parseSrt, renderSrt, renderVtt, type SegmentCue } from "./srt.js";
 import { diagnoseDraftStore, discoverDraftStore } from "./store.js";
-import { formatDuration, formatTime, parseTimeInput, srtTime } from "./time.js";
+import { formatDuration, formatTime, parseTimeInput } from "./time.js";
 import { translateDraft } from "./translate.js";
 import { detectVersion } from "./version.js";
 
@@ -273,7 +274,7 @@ Edit:
   volume     <project> <id> <level>             Set volume (0.0-1.0)
   trim       <project> <id> <start> <duration>  Trim segment (times in seconds)
   opacity    <project> <id> <alpha>             Set opacity (0.0-1.0)
-  export-srt <project>                          Export subtitles to SRT
+  export-srt <project> [options]                Export subtitles to SRT/WebVTT
   batch      <project>                          Run multiple edits from stdin (JSONL)
   restore    <project> [--step N | --list]      Undo writes (latest .bak, or N writes back; --list history)
 
@@ -477,6 +478,16 @@ Subtitles (Phase 3):
                --alpha --vertical --shadow --shadow-color --shadow-distance
                --border-width --border-color --border-alpha
                --bg-color --bg-alpha --bg-style --bg-round-radius --bg-h-offset
+  export-srt <project> [options]
+             Export subtitles to stdout.
+             Options:
+               --granularity <line|word>  One cue per caption (default: line)
+                                          or per word (karaoke).
+               --format <srt|vtt>         SRT (default) or WebVTT. WebVTT word
+                                          cues use inline <timestamps>.
+             Word timings are real where the draft stores them (caption
+             --karaoke word segments); elsewhere they are interpolated within
+             each cue, weighted by word character length.
 
 Navigation: info → tracks/materials → segments → segment <id>
             info → materials --type X → material <id>
@@ -592,6 +603,9 @@ interface Flags {
   maxGapMs?: number;
   noProbe?: boolean;
   ffprobeCmd?: string;
+  // export-srt
+  granularity?: "line" | "word";
+  format?: "srt" | "vtt";
   // quickstart
   video?: string;
   srt?: string;
@@ -871,6 +885,18 @@ function parseFlags(args: string[]): { positional: string[]; flags: Flags } {
       flags.maxGapMs = parseFloat(args[++i]);
     } else if (a === "--no-probe") {
       flags.noProbe = true;
+    } else if (a === "--granularity" && i + 1 < args.length) {
+      const granularity = args[++i];
+      if (!["line", "word"].includes(granularity)) {
+        throw new Error("--granularity must be line|word");
+      }
+      flags.granularity = granularity as Flags["granularity"];
+    } else if (a === "--format" && i + 1 < args.length) {
+      const format = args[++i];
+      if (!["srt", "vtt"].includes(format)) {
+        throw new Error("--format must be srt|vtt");
+      }
+      flags.format = format as Flags["format"];
     } else if (a === "--ffprobe-cmd" && i + 1 < args.length) {
       flags.ffprobeCmd = args[++i];
     } else if (a === "--video" && i + 1 < args.length) {
@@ -1226,20 +1252,38 @@ function cmdOpacity(draft: Draft, filePath: string, segId: string, alphaStr: str
   out({ ok: true, id: result.segment.id, old_opacity: old, new_opacity: alpha }, flags);
 }
 
-function cmdExportSrt(draft: Draft): void {
+function cmdExportSrt(draft: Draft, flags: Flags): void {
+  const granularity = flags.granularity ?? "line";
+  const format = flags.format ?? "srt";
   const textTracks = getTracksByType(draft, "text");
-  const entries: Array<{ start: number; end: number; text: string }> = [];
+  const cues: SegmentCue[] = [];
   for (const track of textTracks) {
+    const entries: SegmentCue[] = [];
     for (const seg of track.segments) {
       const mat = findMaterial(draft.materials.texts, seg.material_id);
       if (!mat) continue;
       const t = seg.target_timerange;
-      entries.push({ start: t.start, end: t.start + t.duration, text: extractText(mat.content) });
+      entries.push({
+        startUs: t.start,
+        endUs: t.start + t.duration,
+        text: extractText(mat.content),
+        styleRanges: extractStyleRanges(mat.content),
+      });
     }
+    // Word granularity: karaoke runs (one word-timed segment per word) carry
+    // real word timings; other cues fall back to length-weighted interpolation.
+    if (granularity === "word") cues.push(...collapseKaraokeRuns(entries));
+    else cues.push(...entries);
+  }
+  cues.sort((a, b) => a.startUs - b.startUs);
+  if (format === "vtt") {
+    process.stdout.write(renderVtt(cues, granularity === "word"));
+  } else if (granularity === "word") {
+    const words = cues.flatMap((c) => cueWords(c).map((w) => ({ startUs: w.startUs, endUs: w.endUs, text: w.word })));
+    process.stdout.write(renderSrt(words));
+  } else {
+    process.stdout.write(renderSrt(cues));
   }
-  entries.sort((a, b) => a.start - b.start);
-  const srt = entries.map((e, i) => `${i + 1}\n${srtTime(e.start)} --> ${srtTime(e.end)}\n${e.text}\n`).join("\n");
-  process.stdout.write(srt);
 }
 
 // --- Discovery & drill-down ---
@@ -2656,7 +2700,7 @@ const SUMMARIES: Record<string, string> = {
   volume: "Set a segment's volume (0.0-1.0).",
   trim: "Trim a segment to a start/duration window.",
   opacity: "Set a segment's opacity (0.0-1.0).",
-  "export-srt": "Export subtitles to SRT on stdout.",
+  "export-srt": "Export subtitles to SRT or WebVTT on stdout, per line or per word.",
   materials: "List material types and counts; filter with --type.",
   segment: "Full detail for one segment and its material.",
   material: "Full detail for one material.",
@@ -3272,7 +3316,7 @@ async function main(): Promise<void> {
       cmdOpacity(draft, filePath, positional[2], positional[3], flags);
       break;
     case "export-srt":
-      cmdExportSrt(draft);
+      cmdExportSrt(draft, flags);
       break;
     case "materials":
       cmdMaterials(draft, flags);
diff --git a/src/srt.ts b/src/srt.ts
index bb02ca4..200893c 100644
--- a/src/srt.ts
+++ b/src/srt.ts
@@ -1,5 +1,5 @@
-// Zero-dep SRT parser. Returns cues with microsecond timings.
-// Format:
+// Zero-dep SRT parser + SRT/WebVTT renderers. Cues carry microsecond timings.
+// Parser format:
 //   1
 //   00:00:01,000 --> 00:00:04,500
 //   line 1
@@ -9,6 +9,8 @@
 //   ...
 // Accepts '.' or ',' as the ms separator. Index lines are optional.
 
+import { srtTime, vttTime } from "./time.js";
+
 export interface SrtCue {
   index: number;
   startUs: number;
@@ -53,3 +55,119 @@ export function parseSrt(content: string): SrtCue[] {
   }
   return cues;
 }
+
+// --- Export (export-srt) ---
+
+export interface SubtitleWord {
+  word: string;
+  startUs: number;
+  endUs: number;
+}
+
+export interface SubtitleCue {
+  startUs: number;
+  endUs: number;
+  text: string;
+  words?: SubtitleWord[]; // real per-word timings when the draft stores them
+}
+
+export interface SegmentCue extends SubtitleCue {
+  styleRanges?: Array<[number, number]>; // UTF-16LE byte ranges from the material's styles
+}
+
+// No stored word timing: spread the cue's duration across its words,
+// weighted by character length. Approximate by construction.
+export function interpolateWords(text: string, startUs: number, endUs: number): SubtitleWord[] {
+  const tokens = Array.from(text.matchAll(/\S+/g), (m) => m[0]);
+  const total = tokens.reduce((n, w) => n + w.length, 0);
+  if (total === 0) return [];
+  const duration = endUs - startUs;
+  let seen = 0;
+  return tokens.map((word) => {
+    const s = startUs + Math.round((duration * seen) / total);
+    seen += word.length;
+    const e = startUs + Math.round((duration * seen) / total);
+    return { word, startUs: s, endUs: e };
+  });
+}
+
+export function cueWords(cue: SubtitleCue): SubtitleWord[] {
+  return cue.words ?? interpolateWords(cue.text, cue.startUs, cue.endUs);
+}
+
+// Karaoke captions (`caption --karaoke`) store one segment PER WORD: full
+// phrase text, word-timed segment, one style range highlighting that word.
+// A run of same-text segments whose highlighted ranges tile the phrase's
+// words in order collapses back into a single cue with real word timings.
+export function collapseKaraokeRuns(entries: SegmentCue[]): SubtitleCue[] {
+  const cues: SubtitleCue[] = [];
+  let i = 0;
+  while (i < entries.length) {
+    let j = i + 1;
+    while (j < entries.length && entries[j].text === entries[i].text) j++;
+    const run = entries.slice(i, j);
+    const words = karaokeWords(run);
+    if (words) {
+      cues.push({
+        startUs: run[0].startUs,
+        endUs: Math.max(...run.map((e) => e.endUs)),
+        text: run[0].text,
+        words,
+      });
+    } else {
+      for (const e of run) cues.push({ startUs: e.startUs, endUs: e.endUs, text: e.text });
+    }
+    i = j;
+  }
+  return cues;
+}
+
+function toUtf16Bytes(text: string, codeUnitIdx: number): number {
+  return Buffer.from(text.slice(0, codeUnitIdx), "utf16le").length;
+}
+
+function karaokeWords(run: SegmentCue[]): SubtitleWord[] | null {
+  if (run.length < 2) return null;
+  const text = run[0].text;
+  const tokens = [...text.matchAll(/\S+/g)];
+  if (tokens.length !== run.length) return null;
+  const words: SubtitleWord[] = [];
+  for (let k = 0; k < run.length; k++) {
+    const tok = tokens[k];
+    const at = tok.index ?? 0;
+    const byteStart = toUtf16Bytes(text, at);
+    const byteEnd = toUtf16Bytes(text, at + tok[0].length);
+    const ranges = run[k].styleRanges ?? [];
+    if (!ranges.some((r) => r[0] === byteStart && r[1] === byteEnd)) return null;
+    if (k > 0 && run[k].startUs < run[k - 1].startUs) return null;
+    words.push({ word: tok[0], startUs: run[k].startUs, endUs: run[k].endUs });
+  }
+  return words;
+}
+
+export function renderSrt(cues: Array<{ startUs: number; endUs: number; text: string }>): string {
+  return cues.map((c, i) => `${i + 1}\n${srtTime(c.startUs)} --> ${srtTime(c.endUs)}\n${c.text}\n`).join("\n");
+}
+
+// Word granularity emits ONE cue per phrase with inline word timestamps
+// (`one <00:00:01.400>two`) — the karaoke form players understand. A leading
+// timestamp is omitted: the first word is active from the cue start.
+export function renderVtt(cues: SubtitleCue[], wordTimestamps: boolean): string {
+  const blocks = cues.map((c) => {
+    const text = wordTimestamps ? vttKaraokeText(c) : c.text;
+    return `${vttTime(c.startUs)} --> ${vttTime(c.endUs)}\n${text}\n`;
+  });
+  return `WEBVTT\n\n${blocks.join("\n")}`;
+}
+
+function vttKaraokeText(cue: SubtitleCue): string {
+  const words = cueWords(cue);
+  if (words.length === 0) return cue.text;
+  return (
+    words[0].word +
+    words
+      .slice(1)
+      .map((w) => ` <${vttTime(w.startUs)}>${w.word}`)
+      .join("")
+  );
+}
diff --git a/src/time.ts b/src/time.ts
index c83d520..1c72826 100644
--- a/src/time.ts
+++ b/src/time.ts
@@ -75,3 +75,8 @@ export function srtTime(us: number): string {
   const ms = Math.round((totalSec % 1) * 1000);
   return `${pad(h)}:${pad(m)}:${pad(s)},${ms.toString().padStart(3, "0")}`;
 }
+
+// WebVTT uses '.' as the millisecond separator.
+export function vttTime(us: number): string {
+  return srtTime(us).replace(",", ".");
+}
diff --git a/test/export-srt.test.mjs b/test/export-srt.test.mjs
new file mode 100644
index 0000000..1ca59e9
--- /dev/null
+++ b/test/export-srt.test.mjs
@@ -0,0 +1,142 @@
+import assert from "node:assert/strict";
+import { join } from "node:path";
+import { after, before, describe, it } from "node:test";
+import { parseSrt } from "../dist/srt.js";
+import { spawnCli } from "./helpers/spawn-cli.mjs";
+import { tmpDir } from "./helpers/tmp-draft.mjs";
+
+function initDraft(dir, name) {
+  const r = spawnCli(["init", name, "--drafts", dir]);
+  assert.equal(r.status, 0, `stderr: ${r.stderr}`);
+  return join(dir, name);
+}
+
+function addText(project, start, duration, text) {
+  const r = spawnCli(["add-text", project, start, duration, text]);
+  assert.equal(r.status, 0, `stderr: ${r.stderr}`);
+  return r.json.segment_id;
+}
+
+describe("export-srt — line granularity (default)", () => {
+  const t = tmpDir();
+  after(() => t.cleanup());
+
+  let project;
+  before(() => {
+    project = initDraft(t.dir, "phrases");
+    const srt = "1\n00:00:01,000 --> 00:00:04,000\nhello brave world\n\n2\n00:00:05,000 --> 00:00:06,000\nbye\n";
+    const r = spawnCli(["import-srt", project, "-"], { input: srt });
+    assert.equal(r.status, 0, `stderr: ${r.stderr}`);
+  });
+
+  it("emits phrase-level SRT and round-trips through parseSrt", () => {
+    const r = spawnCli(["export-srt", project]);
+    assert.equal(r.status, 0, `stderr: ${r.stderr}`);
+    assert.match(r.stdout, /00:00:01,000 --> 00:00:04,000/);
+    const cues = parseSrt(r.stdout);
+    assert.equal(cues.length, 2);
+    assert.equal(cues[0].text, "hello brave world");
+    assert.equal(cues[0].startUs, 1_000_000);
+    assert.equal(cues[0].endUs, 4_000_000);
+  });
+
+  it("--format vtt emits a WEBVTT header with dot milliseconds", () => {
+    const r = spawnCli(["export-srt", project, "--format", "vtt"]);
+    assert.equal(r.status, 0, `stderr: ${r.stderr}`);
+    assert.match(r.stdout, /^WEBVTT\n\n/);
+    assert.match(r.stdout, /00:00:01\.000 --> 00:00:04\.000\nhello brave world/);
+    assert.doesNotMatch(r.stdout, /,\d{3}/);
+  });
+
+  it("--granularity word interpolates cue timings by word length", () => {
+    const r = spawnCli(["export-srt", project, "--granularity", "word"]);
+    assert.equal(r.status, 0, `stderr: ${r.stderr}`);
+    // hello/brave/world are 5 chars each: the 3s cue splits into equal thirds.
+    const cues = parseSrt(r.stdout);
+    assert.equal(cues.length, 4);
+    assert.deepEqual(
+      cues.map((c) => c.text),
+      ["hello", "brave", "world", "bye"],
+    );
+    assert.equal(cues[0].startUs, 1_000_000);
+    assert.equal(cues[0].endUs, 2_000_000);
+    assert.equal(cues[1].startUs, 2_000_000);
+    assert.equal(cues[2].endUs, 4_000_000);
+  });
+});
+
+describe("export-srt — karaoke word timings", () => {
+  const t = tmpDir();
+  after(() => t.cleanup());
+
+  let project;
+  before(() => {
+    // Rebuild what `caption --karaoke` writes (src/caption.ts): one
+    // full-phrase segment per word, word-timed, that word's range highlighted.
+    project = initDraft(t.dir, "karaoke");
+    const words = [
+      ["1s", "0.4s", 0, 3],
+      ["1.4s", "0.4s", 4, 7],
+      ["1.8s", "0.7s", 8, 13],
+    ];
+    for (const [start, duration, from, to] of words) {
+      const id = addText(project, start, duration, "one two three");
+      const styles = JSON.stringify([{ start: from, end: to, font_color: "#FFD700", bold: true }]);
+      const r = spawnCli(["text-ranges", project, id, "--styles", styles]);
+      assert.equal(r.status, 0, `stderr: ${r.stderr}`);
+    }
+  });
+
+  it("exports the stored word timings as one SRT cue per word", () => {
+    const r = spawnCli(["export-srt", project, "--granularity", "word"]);
+    assert.equal(r.status, 0, `stderr: ${r.stderr}`);
+    const cues = parseSrt(r.stdout);
+    assert.deepEqual(
+      cues.map((c) => c.text),
+      ["one", "two", "three"],
+    );
+    // Real stored timings, not length-weighted interpolation.
+    assert.equal(cues[1].startUs, 1_400_000);
+    assert.equal(cues[1].endUs, 1_800_000);
+    assert.equal(cues[2].endUs, 2_500_000);
+  });
+
+  it("emits one VTT cue per phrase with inline word timestamps", () => {
+    const r = spawnCli(["export-srt", project, "--granularity", "word", "--format", "vtt"]);
+    assert.equal(r.status, 0, `stderr: ${r.stderr}`);
+    assert.match(r.stdout, /^WEBVTT\n\n/);
+    assert.match(r.stdout, /00:00:01\.000 --> 00:00:02\.500\none <00:00:01\.400>two <00:00:01\.800>three/);
+  });
+
+  it("keeps line granularity as-is: one cue per stored segment", () => {
+    const r = spawnCli(["export-srt", project]);
+    assert.equal(r.status, 0, `stderr: ${r.stderr}`);
+    const cues = parseSrt(r.stdout);
+    assert.equal(cues.length, 3);
+    for (const cue of cues) assert.equal(cue.text, "one two three");
+  });
+});
+
+describe("export-srt — flag validation and empty drafts", () => {
+  const t = tmpDir();
+  after(() => t.cleanup());
+
+  it("rejects unknown --granularity and --format values", () => {
+    const badGranularity = spawnCli(["export-srt", "unused", "--granularity", "sentence"]);
+    assert.notEqual(badGranularity.status, 0);
+    assert.match(badGranularity.stderr, /--granularity must be line\|word/);
+    const badFormat = spawnCli(["export-srt", "unused", "--format", "ass"]);
+    assert.notEqual(badFormat.status, 0);
+    assert.match(badFormat.stderr, /--format must be srt\|vtt/);
+  });
+
+  it("succeeds with empty output when the draft has no text track", () => {
+    const project = initDraft(t.dir, "no-text");
+    const srt = spawnCli(["export-srt", project, "--granularity", "word"]);
+    assert.equal(srt.status, 0, `stderr: ${srt.stderr}`);
+    assert.equal(srt.stdout, "");
+    const vtt = spawnCli(["export-srt", project, "--format", "vtt"]);
+    assert.equal(vtt.status, 0, `stderr: ${vtt.stderr}`);
+    assert.equal(vtt.stdout, "WEBVTT\n\n");
+  });
+});

From 40dd0deb9e6fa0fcd189f7b1997ff6f1e0c4d99e Mon Sep 17 00:00:00 2001
From: Rene Zander <renezander030@gmail.com>
Date: Wed, 8 Jul 2026 07:40:15 +0000
Subject: [PATCH 04/17] feat(keyframe): easing curves via CapCut FreeCurveInOut
 bezier handles

Add --easing <linear|ease-in|ease-out|ease-in-out> to `capcut keyframe`
(single-shot and --batch, plus a per-line "easing" override on batch
JSONL), an optional easing field on the compile keyframe op, and an
optional [easing] argument on ken-burns.sh.

CapCut UI easing presets are not stored as named curveType values: the
UI writes curveType "FreeCurveInOut" plus bezier control handles on both
keyframes of the eased segment. Handle x is a fixed ratio of the
interval in microseconds (ease-in +0.42, ease-out +0.32/-0.4,
ease-in-out +/-0.42); handle y is 0 except for ease-out, whose outgoing
handle is round(0.94 x delta-value, 6). Encoding, ratios, and rounding
follow the CapCut UI oracle capture validated in
Davidb-2107/capcut-cli-david (cubic-out-triplet-frame-aligned.json):
control.x byte-identical on frame-aligned intervals, within 1us
otherwise, control.y within 1 ULP. Inserting an eased keyframe
retro-updates the facing handles of both neighbours so the easing
applies to both adjacent segments, matching UI behaviour.

ken-burns.sh now DEFAULTS to ease-out instead of linear. The CapCut UI
applies "Cubic Out" to a ken-burns zoom, so the old linear output never
matched what the app itself produces; matching the app is the bug fix.
Pass "linear" as the optional 10th argument for the previous motion.

Keyframes written without easing (or with --easing linear) still emit
the exact "Line" encoding as before, locked by a back-compat test.
---
 .../03-keyframes-and-animations.md            |   3 +-
 skills/capcut-edit/scripts/ken-burns.sh       |  12 +-
 src/command-specs.ts                          |  10 +-
 src/compile.ts                                |   9 +-
 src/decorators.ts                             | 105 ++++++++-
 src/index.ts                                  |  26 ++-
 test/keyframe-easing.test.mjs                 | 206 ++++++++++++++++++
 7 files changed, 351 insertions(+), 20 deletions(-)
 create mode 100644 test/keyframe-easing.test.mjs

diff --git a/docs/draft-schema/03-keyframes-and-animations.md b/docs/draft-schema/03-keyframes-and-animations.md
index 70a3081..a5237ab 100644
--- a/docs/draft-schema/03-keyframes-and-animations.md
+++ b/docs/draft-schema/03-keyframes-and-animations.md
@@ -57,8 +57,9 @@ Per-keyframe interpolation curve to the NEXT keyframe in the list:
 - `"Hold"` — step (no interpolation)
 - `"Smooth"` — ease in/out
 - `"Beizer"` — custom bezier (additional `value_bezier_control_points` field)
+- `"FreeCurveInOut"` — bezier via `left_control` / `right_control` handles; this is what the CapCut UI writes when an easing preset (Cubic In / Cubic Out / …) is applied
 
-`capcut-cli keyframe` writes `"Line"`. Hand-editing is the only path to others today.
+`capcut-cli keyframe` writes `"Line"` by default. With `--easing ease-in|ease-out|ease-in-out` it writes the `"FreeCurveInOut"` encoding: handle `x` is a fixed ratio of the interval to the adjacent keyframe (ease-in `+0.42`, ease-out `+0.32`/`-0.4`, ease-in-out `±0.42`, in microseconds), handle `y` is `0` except ease-out's outgoing handle, which is `round(0.94 × Δvalue, 6)`. Validated against a CapCut UI oracle capture (Davidb-2107/capcut-cli-david).
 
 ### ⚠️ The alpha-keyframes-don't-render trap
 
diff --git a/skills/capcut-edit/scripts/ken-burns.sh b/skills/capcut-edit/scripts/ken-burns.sh
index cc1ba58..37d4850 100755
--- a/skills/capcut-edit/scripts/ken-burns.sh
+++ b/skills/capcut-edit/scripts/ken-burns.sh
@@ -6,12 +6,15 @@
 #     <start-scale> <end-scale> \
 #     <tx-start> <tx-end> \
 #     <ty-start> <ty-end> \
-#     <duration>
+#     <duration> [easing]
 #
 #   <start/end-scale>  uniform scale values (1.0 = no zoom, 1.2 = 20% zoom-in)
 #   <tx-start/tx-end>  horizontal position in half-canvas units (-1..1, 0 = center)
 #   <ty-start/ty-end>  vertical position in half-canvas units (-1..1)
 #   <duration>         time string (e.g. 3s, 500ms)
+#   [easing]           linear | ease-in | ease-out | ease-in-out
+#                      default ease-out — the easing CapCut's own UI applies to
+#                      a ken-burns zoom ("Cubic Out")
 #
 # Writes 6 keyframes total via `capcut keyframe --batch`: uniform_scale,
 # position_x, position_y — each with a start keyframe at t=0 and an end
@@ -20,8 +23,8 @@
 
 set -euo pipefail
 
-if [[ $# -ne 9 ]]; then
-  echo "Usage: $0 <project> <segment-id> <start-scale> <end-scale> <tx-start> <tx-end> <ty-start> <ty-end> <duration>" >&2
+if [[ $# -lt 9 || $# -gt 10 ]]; then
+  echo "Usage: $0 <project> <segment-id> <start-scale> <end-scale> <tx-start> <tx-end> <ty-start> <ty-end> <duration> [easing]" >&2
   exit 2
 fi
 
@@ -34,6 +37,7 @@ tx_end="$6"
 ty_start="$7"
 ty_end="$8"
 duration="$9"
+easing="${10:-ease-out}"
 
 script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 cli="$script_dir/../../../dist/index.js"
@@ -43,7 +47,7 @@ if [[ ! -f "$cli" ]]; then
   exit 1
 fi
 
-node "$cli" keyframe "$project" "$segment_id" --batch <<EOF
+node "$cli" keyframe "$project" "$segment_id" --batch --easing "$easing" <<EOF
 {"property":"uniform_scale","time":"0","value":"$start_scale"}
 {"property":"uniform_scale","time":"$duration","value":"$end_scale"}
 {"property":"position_x","time":"0","value":"$tx_start"}
diff --git a/src/command-specs.ts b/src/command-specs.ts
index aadc1ef..fe784c6 100644
--- a/src/command-specs.ts
+++ b/src/command-specs.ts
@@ -140,7 +140,7 @@ const usages = {
   "add-video": "capcut add-video <project> <file-or-url> <start> [duration] [options]",
   "add-text": "capcut add-text <project> <start> <duration> <text> [options]",
   cut: "capcut cut <project> <start> <end> --out <path>",
-  keyframe: "capcut keyframe <project> <id> <property> <time> <value> | --batch",
+  keyframe: "capcut keyframe <project> <id> <property> <time> <value> [--easing <name>] | --batch",
   transition: "capcut transition <project> <id> <slug> [--duration <time>]",
   mask: "capcut mask <project> <id> <slug> [options] | --off",
   "bg-blur": "capcut bg-blur <project> <id> <level> | --off",
@@ -222,7 +222,13 @@ const optionsByCommand: Record<string, OptionSpec[]> = {
   ],
   "add-text": [TRACK_NAME, ...TEXT_STYLE.slice(0, 5)],
   cut: [OUT],
-  keyframe: [option("batch", ["--batch"], "boolean", "Read JSONL keyframes from stdin.")],
+  keyframe: [
+    option("batch", ["--batch"], "boolean", "Read JSONL keyframes from stdin."),
+    option("easing", ["--easing"], "enum", "Interpolation easing to adjacent keyframes.", {
+      values: ["linear", "ease-in", "ease-out", "ease-in-out"],
+      default: "linear",
+    }),
+  ],
   transition: [option("duration", ["--duration"], "time", "Transition duration.")],
   mask: [
     option("off", ["--off"], "boolean", "Remove masks."),
diff --git a/src/compile.ts b/src/compile.ts
index 861a6b8..6dadcaa 100644
--- a/src/compile.ts
+++ b/src/compile.ts
@@ -114,7 +114,7 @@ export type CompileOperation =
       trackName?: string;
       jianying?: boolean;
     }
-  | { op: "keyframe"; target: string; property: string; time: number; value: number }
+  | { op: "keyframe"; target: string; property: string; time: number; value: number; easing?: string }
   | { op: "audio-fade"; target: string; fadeIn?: number; fadeOut?: number }
   | { op: "text-style"; target: string; style: TextStyleOptions }
   | { op: "text-ranges"; target: string; ranges: TextRangeInput[] }
@@ -439,7 +439,12 @@ export function compileDraft(spec: CompileSpec, opts: CompileOptions): CompileRe
         break;
       case "keyframe":
         addKeyframes(draft, resolveRef(operation.target), [
-          { property: operation.property, timeUs: Math.round(operation.time * US), value: operation.value },
+          {
+            property: operation.property,
+            timeUs: Math.round(operation.time * US),
+            value: operation.value,
+            easing: operation.easing,
+          },
         ]);
         break;
       case "audio-fade":
diff --git a/src/decorators.ts b/src/decorators.ts
index f634d0f..7cbdcd4 100644
--- a/src/decorators.ts
+++ b/src/decorators.ts
@@ -21,6 +21,46 @@ export function keyframeProperties(): string[] {
   return Object.keys(PROPERTY_MAP);
 }
 
+// CapCut's UI easing presets ("Cubic In", "Cubic Out", ...) are NOT stored as
+// named curveType values. The UI writes curveType "FreeCurveInOut" plus bezier
+// control handles on both keyframes of the eased segment: handle x is a fixed
+// ratio of the interval to the adjacent keyframe (microseconds), handle y is 0
+// except for ease-out, which Δ-scales the outgoing handle (see
+// EASE_OUT_RIGHT_Y_RATIO). Ratios and rounding validated byte-for-byte against
+// a CapCut UI oracle capture (Davidb-2107/capcut-cli-david,
+// test-fixtures/oracles/cubic-out-triplet-frame-aligned.json): control.x
+// matches CapCut exactly on frame-aligned intervals and within ±1μs otherwise;
+// control.y within 1 ULP.
+export type EasingName = "linear" | "ease-in" | "ease-out" | "ease-in-out";
+
+interface EasingProfile {
+  startRightXRatio: number; // × interval → segment-start keyframe's right_control.x
+  endLeftXRatio: number; // × interval → segment-end keyframe's left_control.x
+}
+
+const EASING_PROFILES: Record<Exclude<EasingName, "linear">, EasingProfile> = {
+  "ease-in": { startRightXRatio: 0.42, endLeftXRatio: 0 },
+  "ease-out": { startRightXRatio: 0.32, endLeftXRatio: -0.4 },
+  "ease-in-out": { startRightXRatio: 0.42, endLeftXRatio: -0.42 },
+};
+
+// CapCut "Cubic Out" Δ-scales the outgoing handle: right_control.y =
+// round(0.94 × (nextValue − value), 6). A fixed y would only match the UI for
+// one specific value delta.
+const EASE_OUT_RIGHT_Y_RATIO = 0.94;
+
+export function keyframeEasings(): string[] {
+  return ["linear", ...Object.keys(EASING_PROFILES)];
+}
+
+function resolveEasing(easing: string | undefined): EasingName {
+  if (easing === undefined) return "linear";
+  if (easing !== "linear" && !(easing in EASING_PROFILES)) {
+    throw new Error(`Unsupported keyframe easing: ${easing}. Supported: ${keyframeEasings().join(", ")}`);
+  }
+  return easing as EasingName;
+}
+
 export function parseKeyframeValue(property: string, value: string): number {
   if (!(property in PROPERTY_MAP)) {
     throw new Error(`Unsupported keyframe property: ${property}. Supported: ${Object.keys(PROPERTY_MAP).join(", ")}`);
@@ -72,24 +112,78 @@ export interface KeyframeInput {
   property: string;
   timeUs: number; // segment-relative time in microseconds
   value: number; // already parsed/normalised
+  easing?: string; // per-keyframe override of the per-call easing
 }
 
 function uuidHex(): string {
   return randomUUID().replace(/-/g, "");
 }
 
+interface ControlPoint {
+  x: number;
+  y: number;
+}
+
+interface KeyframeEntry {
+  curveType: string;
+  graphID: string;
+  left_control: ControlPoint;
+  right_control: ControlPoint;
+  id: string;
+  time_offset: number;
+  values: number[];
+}
+
 interface KeyframeListObject {
   id: string;
-  keyframe_list: Array<Record<string, unknown>>;
+  keyframe_list: KeyframeEntry[];
   material_id: string;
   property_type: string;
 }
 
+// Stamp the inserted keyframe and retro-update the facing handles of its two
+// neighbours so the easing applies to both adjacent segments — the easing of
+// the inserted keyframe wins, matching CapCut UI behaviour when a preset is
+// applied to a keyframe.
+function applyEasing(list: KeyframeEntry[], entry: KeyframeEntry, easing: Exclude<EasingName, "linear">): void {
+  const profile = EASING_PROFILES[easing];
+  const rightY = (fromValue: number, toValue: number): number =>
+    easing === "ease-out" ? Math.round(EASE_OUT_RIGHT_Y_RATIO * (toValue - fromValue) * 1e6) / 1e6 : 0;
+
+  entry.curveType = "FreeCurveInOut";
+  let prev: KeyframeEntry | undefined;
+  let next: KeyframeEntry | undefined;
+  for (const k of list) {
+    if (k.time_offset < entry.time_offset && (!prev || k.time_offset > prev.time_offset)) prev = k;
+    if (k.time_offset > entry.time_offset && (!next || k.time_offset < next.time_offset)) next = k;
+  }
+  if (prev) {
+    const interval = entry.time_offset - prev.time_offset;
+    prev.curveType = "FreeCurveInOut";
+    prev.right_control = {
+      x: Math.round(profile.startRightXRatio * interval),
+      y: rightY(prev.values[0], entry.values[0]),
+    };
+    entry.left_control = { x: Math.round(profile.endLeftXRatio * interval), y: 0 };
+  }
+  if (next) {
+    const interval = next.time_offset - entry.time_offset;
+    next.curveType = "FreeCurveInOut";
+    next.left_control = { x: Math.round(profile.endLeftXRatio * interval), y: 0 };
+    entry.right_control = {
+      x: Math.round(profile.startRightXRatio * interval),
+      y: rightY(entry.values[0], next.values[0]),
+    };
+  }
+}
+
 export function addKeyframes(
   draft: Draft,
   segmentId: string,
   keyframes: KeyframeInput[],
+  easing?: string,
 ): { segmentId: string; added: number; lists: Array<{ property: string; count: number }> } {
+  resolveEasing(easing); // fail fast even when every keyframe overrides it
   const found = findSegment(draft, segmentId);
   if (!found) throw new Error(`Segment not found: ${segmentId}`);
   const seg = found.segment as Segment & { common_keyframes?: unknown };
@@ -106,6 +200,7 @@ export function addKeyframes(
         `Unsupported keyframe property: ${kf.property}. Supported: ${Object.keys(PROPERTY_MAP).join(", ")}`,
       );
     }
+    const kfEasing = resolveEasing(kf.easing ?? easing);
     let list = commonKeyframes.find((l) => l.property_type === propEnum);
     if (!list) {
       list = {
@@ -116,7 +211,7 @@ export function addKeyframes(
       };
       commonKeyframes.push(list);
     }
-    list.keyframe_list.push({
+    const entry: KeyframeEntry = {
       curveType: "Line",
       graphID: "",
       left_control: { x: 0.0, y: 0.0 },
@@ -124,8 +219,10 @@ export function addKeyframes(
       id: uuidHex(),
       time_offset: kf.timeUs,
       values: [kf.value],
-    });
-    list.keyframe_list.sort((a, b) => (a.time_offset as number) - (b.time_offset as number));
+    };
+    if (kfEasing !== "linear") applyEasing(list.keyframe_list, entry, kfEasing);
+    list.keyframe_list.push(entry);
+    list.keyframe_list.sort((a, b) => a.time_offset - b.time_offset);
   }
 
   const summary = commonKeyframes.map((l) => {
diff --git a/src/index.ts b/src/index.ts
index 6199323..952ad9a 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -297,14 +297,17 @@ Maintenance & inspection:
              attach to a version-support issue like #35.
 
 Animate:
-  keyframe   <project> <id> <property> <time> <value>
+  keyframe   <project> <id> <property> <time> <value> [--easing <name>]
              Add a keyframe to a segment. Single-shot.
-  keyframe   <project> <id> --batch
-             Read JSONL from stdin; each line = {"property","time","value"}.
+  keyframe   <project> <id> --batch [--easing <name>]
+             Read JSONL from stdin; each line = {"property","time","value"}
+             plus optional "easing" overriding --easing per line.
              Properties: position_x, position_y, rotation, scale_x, scale_y,
                          uniform_scale, alpha, saturation, contrast, brightness, volume
              Values: "1.5", "50%" (alpha/volume), "45deg" (rotation),
                      "+0.5"/"-0.3" (saturation/contrast/brightness)
+             Easing: linear (default), ease-in, ease-out, ease-in-out — written
+                     as CapCut bezier handles (ease-out = the UI's "Cubic Out")
 
   transition <project> <id> <slug> [--duration <s>]
              Attach a transition to a video/image segment. Slug examples:
@@ -508,6 +511,8 @@ interface Flags {
   volume?: number;
   template?: string;
   drafts?: string;
+  // keyframe
+  easing?: string;
   // Phase 1 decorators
   duration?: string;
   off?: boolean;
@@ -705,7 +710,9 @@ function parseFlags(args: string[]): { positional: string[]; flags: Flags } {
     else if (a === "-v" || a === "--version") flags.version = true;
     else if (a === "-q" || a === "--quiet") flags.quiet = true;
     else if (a === "--batch") flags.batch = true;
-    else if ((a === "--track" || a === "--type") && i + 1 < args.length) {
+    else if (a === "--easing" && i + 1 < args.length) {
+      flags.easing = args[++i];
+    } else if ((a === "--track" || a === "--type") && i + 1 < args.length) {
       flags.track = args[++i];
     } else if (a === "--out" && i + 1 < args.length) {
       flags.out = args[++i];
@@ -1501,13 +1508,18 @@ function cmdKeyframe(draft: Draft, filePath: string, positional: string[], flags
     for (const line of raw.split("\n")) {
       const trimmed = line.trim();
       if (!trimmed) continue;
-      const op = JSON.parse(trimmed) as { property?: string; time?: string | number; value?: string | number };
+      const op = JSON.parse(trimmed) as {
+        property?: string;
+        time?: string | number;
+        value?: string | number;
+        easing?: string;
+      };
       if (!op.property || op.time === undefined || op.value === undefined) {
         die(`batch keyframe requires {property, time, value} per line; got: ${trimmed}`);
       }
       const timeUs = typeof op.time === "number" ? op.time : parseTimeInput(op.time);
       const value = parseKeyframeValue(op.property, String(op.value));
-      inputs.push({ property: op.property, timeUs, value });
+      inputs.push({ property: op.property, timeUs, value, easing: op.easing });
     }
   } else {
     const property = positional[3];
@@ -1523,7 +1535,7 @@ function cmdKeyframe(draft: Draft, filePath: string, positional: string[], flags
     inputs.push({ property, timeUs, value });
   }
 
-  const result = addKeyframes(draft, segId, inputs);
+  const result = addKeyframes(draft, segId, inputs, flags.easing);
   saveDraft(filePath, draft);
   out({ ok: true, id: result.segmentId, added: result.added, lists: result.lists }, flags);
 }
diff --git a/test/keyframe-easing.test.mjs b/test/keyframe-easing.test.mjs
new file mode 100644
index 0000000..0ca9d7b
--- /dev/null
+++ b/test/keyframe-easing.test.mjs
@@ -0,0 +1,206 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { after, describe, it } from "node:test";
+import { fileURLToPath } from "node:url";
+import { spawnCli } from "./helpers/spawn-cli.mjs";
+import { tmpDraft } from "./helpers/tmp-draft.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const KEN_BURNS = join(__dirname, "..", "skills", "capcut-edit", "scripts", "ken-burns.sh");
+
+// First video segment of the canonical fixture (see test/draft_content.json).
+const SEG = "aaaaaa01";
+const SEG_FULL = "aaaaaa01-0000-0000-0000-000000000001";
+
+function keyframeList(path, propertyType, segId = SEG_FULL) {
+  const draft = JSON.parse(readFileSync(path, "utf-8"));
+  for (const track of draft.tracks) {
+    const seg = track.segments.find((s) => s.id === segId);
+    if (!seg) continue;
+    return (seg.common_keyframes ?? []).find((l) => l.property_type === propertyType)?.keyframe_list ?? [];
+  }
+  return [];
+}
+
+const HEX32 = /^[0-9a-f]{32}$/;
+
+describe("keyframe --easing: snapshot encodings", () => {
+  const fix = tmpDraft();
+  after(() => fix.cleanup());
+
+  it("back-compat: no easing still writes the Line encoding", () => {
+    const r = spawnCli(["keyframe", fix.path, SEG, "alpha", "0s", "0.5"]);
+    assert.equal(r.status, 0, `stderr: ${r.stderr}`);
+    const list = keyframeList(fix.path, "KFTypeAlpha");
+    assert.equal(list.length, 1);
+    assert.match(list[0].id, HEX32);
+    assert.deepEqual(list[0], {
+      curveType: "Line",
+      graphID: "",
+      left_control: { x: 0, y: 0 },
+      right_control: { x: 0, y: 0 },
+      id: list[0].id,
+      time_offset: 0,
+      values: [0.5],
+    });
+  });
+
+  it("--easing linear writes the same Line encoding as no easing", () => {
+    const r = spawnCli(["keyframe", fix.path, SEG, "rotation", "1s", "45deg", "--easing", "linear"]);
+    assert.equal(r.status, 0, `stderr: ${r.stderr}`);
+    const list = keyframeList(fix.path, "KFTypeRotation");
+    assert.deepEqual(list[0], {
+      curveType: "Line",
+      graphID: "",
+      left_control: { x: 0, y: 0 },
+      right_control: { x: 0, y: 0 },
+      id: list[0].id,
+      time_offset: 1000000,
+      values: [45],
+    });
+  });
+
+  // Bezier handle profiles per easing for a 1.0 -> 1.3 pair over 5s:
+  //   handle x = ratio × interval; ease-out's outgoing y = round(0.94 × Δ, 6).
+  // Ratios from the CapCut UI oracle in Davidb-2107/capcut-cli-david.
+  const PAIR_SNAPSHOTS = [
+    ["ease-in", "scale_x", "KFTypeScaleX", { x: 2100000, y: 0 }, { x: 0, y: 0 }],
+    ["ease-out", "scale_y", "KFTypeScaleY", { x: 1600000, y: 0.282 }, { x: -2000000, y: 0 }],
+    ["ease-in-out", "position_x", "KFTypePositionX", { x: 2100000, y: 0 }, { x: -2100000, y: 0 }],
+  ];
+
+  for (const [easing, property, propertyType, startRight, endLeft] of PAIR_SNAPSHOTS) {
+    it(`--easing ${easing} writes the FreeCurveInOut handle pair`, () => {
+      const lines = [
+        JSON.stringify({ property, time: 0, value: "1.0" }),
+        JSON.stringify({ property, time: 5000000, value: "1.3" }),
+      ].join("\n");
+      const r = spawnCli(["keyframe", fix.path, SEG, "--batch", "--easing", easing], { input: lines });
+      assert.equal(r.status, 0, `stderr: ${r.stderr}`);
+      const list = keyframeList(fix.path, propertyType);
+      assert.equal(list.length, 2);
+      assert.deepEqual(list[0], {
+        curveType: "FreeCurveInOut",
+        graphID: "",
+        left_control: { x: 0, y: 0 },
+        right_control: startRight,
+        id: list[0].id,
+        time_offset: 0,
+        values: [1],
+      });
+      assert.deepEqual(list[1], {
+        curveType: "FreeCurveInOut",
+        graphID: "",
+        left_control: endLeft,
+        right_control: { x: 0, y: 0 },
+        id: list[1].id,
+        time_offset: 5000000,
+        values: [1.3],
+      });
+    });
+  }
+
+  it("per-line easing in --batch overrides the --easing flag", () => {
+    const lines = [
+      JSON.stringify({ property: "contrast", time: 0, value: "0", easing: "ease-out" }),
+      JSON.stringify({ property: "contrast", time: 2000000, value: "+0.5", easing: "ease-out" }),
+    ].join("\n");
+    const r = spawnCli(["keyframe", fix.path, SEG, "--batch", "--easing", "linear"], { input: lines });
+    assert.equal(r.status, 0, `stderr: ${r.stderr}`);
+    const list = keyframeList(fix.path, "KFTypeContrast");
+    assert.equal(list[0].curveType, "FreeCurveInOut");
+    assert.deepEqual(list[0].right_control, { x: 640000, y: 0.47 });
+    assert.deepEqual(list[1].left_control, { x: -800000, y: 0 });
+  });
+});
+
+describe("keyframe --easing: ease-out oracle replay", () => {
+  const fix = tmpDraft();
+  after(() => fix.cleanup());
+
+  // Replays the CapCut UI oracle capture from Davidb-2107/capcut-cli-david
+  // (test-fixtures/oracles/cubic-out-triplet-frame-aligned.json): 3 scale_x
+  // keyframes at 0 / 5s / 8.133333s with values 1.0 / 1.3 / 1.0, ease-out
+  // applied per keyframe. Inserting the third keyframe must retro-update the
+  // second one's outgoing handle for the new 3_133_333μs interval.
+  // CapCut's own bytes are x=1002666 / x=-1253334 on the non-frame-aligned
+  // interval; Math.round lands within the oracle's documented ±1μs tolerance.
+  it("incremental inserts retro-update neighbour handles like the UI", () => {
+    const inputs = [
+      { time: 0, value: "1.0" },
+      { time: 5000000, value: "1.3" },
+      { time: 8133333, value: "1.0" },
+    ];
+    for (const { time, value } of inputs) {
+      const line = JSON.stringify({ property: "scale_x", time, value, easing: "ease-out" });
+      const r = spawnCli(["keyframe", fix.path, SEG, "--batch"], { input: line });
+      assert.equal(r.status, 0, `stderr: ${r.stderr}`);
+    }
+    const list = keyframeList(fix.path, "KFTypeScaleX");
+    assert.equal(list.length, 3);
+    const controls = list.map((k) => ({ left: k.left_control, right: k.right_control }));
+    assert.deepEqual(controls, [
+      { left: { x: 0, y: 0 }, right: { x: 1600000, y: 0.282 } },
+      { left: { x: -2000000, y: 0 }, right: { x: 1002667, y: -0.282 } },
+      { left: { x: -1253333, y: 0 }, right: { x: 0, y: 0 } },
+    ]);
+    assert.ok(list.every((k) => k.curveType === "FreeCurveInOut"));
+  });
+});
+
+describe("keyframe --easing: rejection", () => {
+  const fix = tmpDraft();
+  after(() => fix.cleanup());
+
+  it("rejects an unknown easing on the flag", () => {
+    const r = spawnCli(["keyframe", fix.path, SEG, "alpha", "0s", "0.5", "--easing", "bounce"]);
+    assert.equal(r.status, 1);
+    assert.match(r.stderr, /Unsupported keyframe easing: bounce/);
+    assert.match(r.stderr, /linear, ease-in, ease-out, ease-in-out/);
+  });
+
+  it("rejects an unknown easing on a batch line", () => {
+    const line = JSON.stringify({ property: "alpha", time: 0, value: "0.5", easing: "elastic" });
+    const r = spawnCli(["keyframe", fix.path, SEG, "--batch"], { input: line });
+    assert.equal(r.status, 1);
+    assert.match(r.stderr, /Unsupported keyframe easing: elastic/);
+  });
+});
+
+describe("ken-burns.sh easing default", () => {
+  function runKenBurns(fix, extra = []) {
+    return spawnSync("bash", [KEN_BURNS, fix.path, SEG, "1.0", "1.2", "0", "-0.1", "0", "-0.05", "3s", ...extra], {
+      encoding: "utf-8",
+    });
+  }
+
+  it("defaults to ease-out — the easing CapCut's UI applies to a ken-burns zoom", () => {
+    const fix = tmpDraft();
+    after(() => fix.cleanup());
+    const r = runKenBurns(fix);
+    assert.equal(r.status, 0, `stderr: ${r.stderr}`);
+    const list = keyframeList(fix.path, "UNIFORM_SCALE");
+    assert.equal(list.length, 2);
+    assert.equal(list[0].curveType, "FreeCurveInOut");
+    // 0.32 × 3s and round(0.94 × (1.2 − 1.0), 6)
+    assert.deepEqual(list[0].right_control, { x: 960000, y: 0.188 });
+    assert.deepEqual(list[1].left_control, { x: -1200000, y: 0 });
+    // position keyframes get the same treatment, Δ-scaled per property
+    const px = keyframeList(fix.path, "KFTypePositionX");
+    assert.deepEqual(px[0].right_control, { x: 960000, y: -0.094 });
+  });
+
+  it("explicit linear argument keeps the legacy Line encoding", () => {
+    const fix = tmpDraft();
+    after(() => fix.cleanup());
+    const r = runKenBurns(fix, ["linear"]);
+    assert.equal(r.status, 0, `stderr: ${r.stderr}`);
+    const list = keyframeList(fix.path, "UNIFORM_SCALE");
+    assert.equal(list.length, 2);
+    assert.equal(list[0].curveType, "Line");
+    assert.deepEqual(list[0].right_control, { x: 0, y: 0 });
+    assert.deepEqual(list[1].left_control, { x: 0, y: 0 });
+  });
+});

From 368a819007e2c54f6447c224cf1e72d1f77b78d3 Mon Sep 17 00:00:00 2001
From: Rene Zander <renezander030@gmail.com>
Date: Wed, 8 Jul 2026 07:52:53 +0000
Subject: [PATCH 05/17] feat(detect-scenes): deterministic ffmpeg scene-cut
 detection to seed long-form-to-shorts splits
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds 'capcut detect-scenes <video>' — runs ffmpeg's scene-change score
(select='gt(scene,T)' + metadata=print, parsing pts_time and
lavfi.scene_score from stderr) over a raw video and prints cut points
(seconds + hh:mm:ss.mmm + score) plus the resulting segment list in both
seconds and draft-native microseconds, ready to feed into compile/cut.
No AI, no new deps; the external-binary handling mirrors render/probe
(pure, unit-testable parsing + an actionable error when ffmpeg is
missing or the file does not exist).

  --threshold <0..1>  scene score a cut must exceed (default 0.4)
  --min-gap <s>       merge cuts closer than the gap, keeping the
                      strongest (default 2)
  --limit <n>         keep only the N strongest cuts
  --ffmpeg-cmd <p>    ffmpeg binary override
  --json              force JSON (the repo default; overrides -H)

Detection only — draft mutation stays with compile/cut/quickstart.

Ecosystem ask: GuanYixuan/pyJianYingDraft#191 (content-aware cut points).
---
 src/command-specs.ts        |  14 ++-
 src/index.ts                |  82 ++++++++++++
 src/scenes.ts               | 209 +++++++++++++++++++++++++++++++
 test/detect-scenes.test.mjs | 242 ++++++++++++++++++++++++++++++++++++
 4 files changed, 545 insertions(+), 2 deletions(-)
 create mode 100644 src/scenes.ts
 create mode 100644 test/detect-scenes.test.mjs

diff --git a/src/command-specs.ts b/src/command-specs.ts
index aadc1ef..00c2cf8 100644
--- a/src/command-specs.ts
+++ b/src/command-specs.ts
@@ -187,6 +187,7 @@ const usages = {
   quickstart: "capcut quickstart <name> [--video <f>] [--audio <f>] [--srt <f>] [--drafts <dir>]",
   compile: "capcut compile <spec.json> [--out <draftdir>] [--check | --plan]",
   render: "capcut render <project> [--out <preview.mp4>] [options]",
+  "detect-scenes": "capcut detect-scenes <video> [options]",
 } as const satisfies Record<string, string>;
 
 export type CommandName = keyof typeof usages;
@@ -384,6 +385,15 @@ const optionsByCommand: Record<string, OptionSpec[]> = {
     option("burn_captions", ["--burn-captions"], "boolean", "Burn captions."),
     option("all_video_tracks", ["--all-video-tracks"], "boolean", "Composite every video track."),
   ],
+  "detect-scenes": [
+    option("threshold", ["--threshold"], "number", "Scene-change score a cut must exceed (0..1).", { default: 0.4 }),
+    option("min_gap", ["--min-gap"], "number", "Merge cuts closer than this many seconds, keeping the strongest.", {
+      default: 2,
+    }),
+    option("limit", ["--limit"], "number", "Keep only the N strongest cuts."),
+    option("ffmpeg_cmd", ["--ffmpeg-cmd"], "path", "FFmpeg binary."),
+    option("json", ["--json"], "boolean", "Force JSON output (the default; overrides -H)."),
+  ],
 };
 optionsByCommand["image-anim"] = optionsByCommand["text-anim"];
 
@@ -439,7 +449,7 @@ const textOutputs = new Set(["export-srt", "completions"]);
 const fileOutputs = new Set(["render", "translate", "compile", "cut", "save-template"]);
 
 function inferType(name: string): ArgumentType {
-  if (/project|file|path|dir|template|audio|image|srt|ass|spec|draft/i.test(name)) return "path";
+  if (/project|file|path|dir|template|audio|video|image|srt|ass|spec|draft/i.test(name)) return "path";
   if (/^(id|segment-id|resource-id)$/.test(name)) return "id";
   if (/start|end|duration|offset|time/.test(name)) return "time";
   if (/level|multiplier|alpha|value/.test(name)) return "number";
@@ -472,7 +482,7 @@ export function buildCommandSpecs(commands: readonly string[], summaries: Record
   return commands.map((name) => {
     const usage = usages[name as CommandName] ?? `capcut ${name} <project>`;
     const prerequisites: string[] = [];
-    if (name === "render") prerequisites.push("ffmpeg");
+    if (name === "render" || name === "detect-scenes") prerequisites.push("ffmpeg");
     if (["add-video", "add-audio", "compile"].includes(name)) prerequisites.push("ffprobe (optional)");
     if (name === "caption") prerequisites.push("whisper CLI");
     if (name === "translate") prerequisites.push("ANTHROPIC_API_KEY or --api-key");
diff --git a/src/index.ts b/src/index.ts
index 6199323..a1a7afc 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -86,6 +86,7 @@ import { probeMedia } from "./probe.js";
 import { runQuickstart } from "./quickstart.js";
 import { buildRenderPlan, renderDraft } from "./render.js";
 import { replaceMedia } from "./replace.js";
+import { detectScenes, timecode } from "./scenes.js";
 import { serveQueue } from "./serve.js";
 import { addSfx } from "./sfx.js";
 import { parseSrt } from "./srt.js";
@@ -164,6 +165,7 @@ export const COMMANDS = [
   "quickstart",
   "compile",
   "render",
+  "detect-scenes",
 ] as const;
 
 const HELP = `capcut-cli -- fast edits to CapCut projects
@@ -236,6 +238,22 @@ Preview:
                --ffmpeg-cmd <p>   ffmpeg binary (default ffmpeg)
                --dry-run          Print the ffmpeg plan; do not execute
 
+Analyze:
+  detect-scenes <video> [--threshold <n>] [--min-gap <s>] [--limit <n>]
+             Detect scene-change cut points in a raw video file (ffmpeg scene
+             filter — deterministic, no draft needed). Prints each cut as
+             seconds + hh:mm:ss.mmm + score, plus the resulting segment list
+             in seconds AND microseconds (the draft-native unit), ready to
+             seed a long-form-to-shorts split: feed the segments into
+             "capcut compile" (one clip per segment) or "capcut cut".
+             Detection only — it never touches a draft. Options:
+               --threshold <n>    Scene score a cut must exceed, 0..1 (default 0.4)
+               --min-gap <s>      Merge cuts closer than <s> seconds, keeping
+                                  the strongest (default 2)
+               --limit <n>        Keep only the <n> strongest cuts
+               --ffmpeg-cmd <p>   ffmpeg binary (default ffmpeg)
+               --json             Force JSON output (the default; overrides -H)
+
 Add:
   add-audio  <project> <file-or-wikimedia-url> <start> <duration> [options]
              Add an audio segment (VO, music, SFX). URLs to wikipedia.org /
@@ -633,6 +651,11 @@ interface Flags {
   continueOnError?: boolean;
   check?: boolean;
   plan?: boolean;
+  // detect-scenes
+  threshold?: number;
+  minGap?: number;
+  limit?: number;
+  json?: boolean;
 }
 
 // Map CLI enum flags -> enums.json category key. Order matters for HELP text.
@@ -935,6 +958,14 @@ function parseFlags(args: string[]): { positional: string[]; flags: Flags } {
       flags.check = true;
     } else if (a === "--plan") {
       flags.plan = true;
+    } else if (a === "--threshold" && i + 1 < args.length) {
+      flags.threshold = parseFloat(args[++i]);
+    } else if (a === "--min-gap" && i + 1 < args.length) {
+      flags.minGap = parseFloat(args[++i]);
+    } else if (a === "--limit" && i + 1 < args.length) {
+      flags.limit = parseInt(args[++i], 10);
+    } else if (a === "--json") {
+      flags.json = true;
     } else {
       const hit = ENUM_FLAG_MAP.find((f) => f.flag === a);
       if (hit) {
@@ -2709,6 +2740,8 @@ const SUMMARIES: Record<string, string> = {
   init: "Create a new empty draft from a template.",
   compile: "Build a draft from a declarative JSON spec (the inverse of describe).",
   render: "Render a low-res ffmpeg proxy preview (trim+speed+audio, --burn-captions); not CapCut's final render.",
+  "detect-scenes":
+    "Detect scene-change cut points in a video (ffmpeg scene filter); prints cuts + segments to seed compile/cut.",
 };
 
 // `describe` emits a machine-readable tool spec for LLM/agent callers, so they
@@ -2998,6 +3031,49 @@ function cmdRender(draft: Draft, filePath: string, flags: Flags): void {
   if (!flags.quiet) process.stderr.write(`Rendered: ${result.output}\n`);
 }
 
+function cmdDetectScenes(positional: string[], flags: Flags): void {
+  const videoPath = positional[1];
+  if (!videoPath) {
+    die("Missing video. Usage: capcut detect-scenes <video> [--threshold <0..1>] [--min-gap <seconds>] [--limit <n>]");
+  }
+  const threshold = flags.threshold ?? 0.4;
+  if (!Number.isFinite(threshold) || threshold <= 0 || threshold > 1) die("--threshold must be in (0, 1]");
+  const minGap = flags.minGap ?? 2;
+  if (!Number.isFinite(minGap) || minGap < 0) die("--min-gap must be >= 0 seconds");
+  if (flags.limit !== undefined && (!Number.isFinite(flags.limit) || flags.limit < 1)) {
+    die("--limit must be a positive integer");
+  }
+  const report = detectScenes(videoPath, {
+    threshold,
+    minGap,
+    limit: flags.limit,
+    ffmpegCmd: flags.ffmpegCmd,
+  });
+  // --json forces machine output even when a config/alias turned on --human.
+  if (flags.human && !flags.json) {
+    console.log(`Video:     ${report.video}`);
+    console.log(`Duration:  ${report.duration === null ? "unknown" : formatDuration(report.duration_us ?? 0)}`);
+    console.log(
+      `Threshold: ${report.threshold}  (min gap ${report.min_gap}s${report.limit ? `, limit ${report.limit}` : ""})`,
+    );
+    console.log(`Cuts:      ${report.cuts.length}`);
+    for (const [i, c] of report.cuts.entries()) {
+      console.log(`  ${String(i + 1).padStart(3)}  ${c.timecode}  score ${c.score.toFixed(3)}`);
+    }
+    console.log(`Segments:  ${report.segments.length}`);
+    for (const [i, s] of report.segments.entries()) {
+      const end = s.end === null ? "end" : timecode(s.end);
+      const dur = s.duration_us === null ? "?" : formatDuration(s.duration_us);
+      console.log(`  ${String(i + 1).padStart(3)}  ${timecode(s.start)} - ${end}  ${dur}`);
+    }
+    console.log(
+      "Next: pipe the segments into `capcut compile` (one clip per segment) or `capcut cut` to split the video.",
+    );
+    return;
+  }
+  out(report, flags);
+}
+
 // --- Main ---
 
 async function main(): Promise<void> {
@@ -3202,6 +3278,12 @@ async function main(): Promise<void> {
     process.exit(0);
   }
 
+  // `detect-scenes` analyzes a raw video file for cut points — no draft needed.
+  if (cmd === "detect-scenes") {
+    cmdDetectScenes(positional, flags);
+    process.exit(0);
+  }
+
   if (!projectPath) die("Missing project path. Run 'capcut --help' for usage.");
 
   const { draft, filePath } = loadDraft(projectPath);
diff --git a/src/scenes.ts b/src/scenes.ts
new file mode 100644
index 0000000..63ea019
--- /dev/null
+++ b/src/scenes.ts
@@ -0,0 +1,209 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+
+/**
+ * Deterministic scene-cut detection (ffmpeg scene filter, no AI).
+ *
+ * Seeds the cut-long-form-to-shorts workflow: a raw recording is opaque until
+ * you know where the content-aware cut points are (pyJianYingDraft#191 asks
+ * for exactly this). `detect-scenes` runs ffmpeg's scene-change score over a
+ * video — select='gt(scene,T)' + metadata=print writes each selected frame's
+ * pts_time and lavfi.scene_score to stderr — and turns that into cut points
+ * plus a ready-to-use segment list (seconds + draft-native microseconds).
+ *
+ * Architecture mirrors `probe`/`render`: parsing and cut/segment math are
+ * pure, deterministic functions (`parseSceneCuts`, `parseFfmpegDuration`,
+ * `mergeCloseCuts`, `limitCuts`, `buildSceneSegments`) tests assert without
+ * invoking ffmpeg; the live shell-out (`detectScenes`) throws an actionable
+ * error when ffmpeg is missing, matching render's behavior.
+ */
+
+const US = 1_000_000; // microseconds per second — CapCut's timing unit
+
+export interface SceneCut {
+  time: number; // seconds
+  score: number; // ffmpeg scene score, 0..1
+}
+
+export interface SceneSegment {
+  start: number;
+  end: number | null; // null when the source duration is unknown
+  duration: number | null;
+  start_us: number;
+  end_us: number | null;
+  duration_us: number | null;
+}
+
+export interface SceneDetectOptions {
+  threshold?: number; // scene score a frame must exceed (default 0.4)
+  minGap?: number; // merge cuts closer than this many seconds (default 2)
+  limit?: number; // keep only the N strongest cuts
+  ffmpegCmd?: string; // ffmpeg binary (default "ffmpeg")
+}
+
+export interface SceneReport {
+  video: string;
+  threshold: number;
+  min_gap: number;
+  limit: number | null;
+  duration: number | null;
+  duration_us: number | null;
+  cuts: Array<{ time: number; time_us: number; timecode: string; score: number }>;
+  segments: SceneSegment[];
+}
+
+/**
+ * Parse the stderr of `-vf select='gt(scene,T)',metadata=print -f null -`.
+ * Each selected frame emits two lines:
+ *   [Parsed_metadata_1 @ 0x...] frame:0  pts:15360  pts_time:1.024
+ *   [Parsed_metadata_1 @ 0x...] lavfi.scene_score=0.400000
+ */
+export function parseSceneCuts(stderr: string): SceneCut[] {
+  const cuts: SceneCut[] = [];
+  let pending: number | null = null;
+  for (const line of stderr.split("\n")) {
+    const time = line.match(/\bpts_time:(-?\d+(?:\.\d+)?)/);
+    if (time) {
+      pending = Number(time[1]);
+      continue;
+    }
+    const score = line.match(/lavfi\.scene_score=(\d+(?:\.\d+)?)/);
+    if (score && pending !== null) {
+      // A cut at t<=0 has no preceding frame to cut away from.
+      if (pending > 0) cuts.push({ time: pending, score: Number(score[1]) });
+      pending = null;
+    }
+  }
+  return cuts.sort((a, b) => a.time - b.time);
+}
+
+/** Pull the input duration off ffmpeg's stderr header ("Duration: 00:00:03.00, ..."). */
+export function parseFfmpegDuration(stderr: string): number | null {
+  const m = stderr.match(/Duration:\s*(\d+):(\d{2}):(\d+(?:\.\d+)?)/);
+  if (!m) return null;
+  return Number(m[1]) * 3600 + Number(m[2]) * 60 + Number(m[3]);
+}
+
+/**
+ * Merge cuts closer than `minGap` seconds. Chains of close cuts collapse into
+ * one cluster; the strongest cut (earliest on ties) represents each cluster.
+ */
+export function mergeCloseCuts(cuts: SceneCut[], minGap: number): SceneCut[] {
+  if (minGap <= 0 || cuts.length < 2) return [...cuts].sort((a, b) => a.time - b.time);
+  const sorted = [...cuts].sort((a, b) => a.time - b.time);
+  const merged: SceneCut[] = [];
+  let best = sorted[0];
+  let prevTime = sorted[0].time;
+  for (const cut of sorted.slice(1)) {
+    if (cut.time - prevTime < minGap) {
+      if (cut.score > best.score) best = cut;
+    } else {
+      merged.push(best);
+      best = cut;
+    }
+    prevTime = cut.time;
+  }
+  merged.push(best);
+  return merged;
+}
+
+/** Keep the N strongest cuts (earliest wins ties), returned back in time order. */
+export function limitCuts(cuts: SceneCut[], limit: number | undefined): SceneCut[] {
+  if (limit === undefined || cuts.length <= limit) return cuts;
+  return [...cuts]
+    .sort((a, b) => b.score - a.score || a.time - b.time)
+    .slice(0, limit)
+    .sort((a, b) => a.time - b.time);
+}
+
+/**
+ * Turn cut points into contiguous segments [0..cut1][cut1..cut2][..duration].
+ * With an unknown duration the trailing segment is open-ended (end null).
+ */
+export function buildSceneSegments(cuts: SceneCut[], duration: number | null): SceneSegment[] {
+  const bounded = duration === null ? cuts : cuts.filter((c) => c.time < duration);
+  const starts = [0, ...bounded.map((c) => c.time)];
+  return starts.map((start, i) => {
+    const end = i + 1 < starts.length ? starts[i + 1] : duration;
+    return {
+      start,
+      end,
+      duration: end === null ? null : round6(end - start),
+      start_us: Math.round(start * US),
+      end_us: end === null ? null : Math.round(end * US),
+      duration_us: end === null ? null : Math.round(end * US) - Math.round(start * US),
+    };
+  });
+}
+
+/** Format seconds as hh:mm:ss.mmm. */
+export function timecode(seconds: number): string {
+  const h = Math.floor(seconds / 3600);
+  const m = Math.floor((seconds % 3600) / 60);
+  const s = seconds % 60;
+  const pad = (n: number) => n.toString().padStart(2, "0");
+  return `${pad(h)}:${pad(m)}:${s.toFixed(3).padStart(6, "0")}`;
+}
+
+function round6(n: number): number {
+  return Math.round(n * 1_000_000) / 1_000_000;
+}
+
+/**
+ * Live detection. Runs ffmpeg's scene filter over `videoPath` and assembles
+ * the report. Throws with an actionable message when the file or ffmpeg is
+ * missing, or when ffmpeg fails (mirrors render's error style).
+ */
+export function detectScenes(videoPath: string, opts: SceneDetectOptions = {}): SceneReport {
+  const threshold = opts.threshold ?? 0.4;
+  const minGap = opts.minGap ?? 2;
+  const cmd = opts.ffmpegCmd ?? "ffmpeg";
+  if (!existsSync(videoPath)) {
+    throw new Error(`detect-scenes: video not found: ${videoPath}`);
+  }
+  const args = [
+    "-hide_banner",
+    "-i",
+    videoPath,
+    "-vf",
+    `select='gt(scene,${threshold})',metadata=print`,
+    "-an",
+    "-f",
+    "null",
+    "-",
+  ];
+  let r: ReturnType<typeof spawnSync>;
+  try {
+    r = spawnSync(cmd, args, { encoding: "utf-8", timeout: 600_000, maxBuffer: 64 * 1024 * 1024 });
+  } catch (e) {
+    throw new Error(
+      `detect-scenes: ffmpeg is unavailable at '${cmd}'. Install ffmpeg or pass --ffmpeg-cmd <path>. (${
+        e instanceof Error ? e.message : String(e)
+      })`,
+    );
+  }
+  if (r.error) {
+    throw new Error(`detect-scenes: ffmpeg is unavailable at '${cmd}'. Install ffmpeg or pass --ffmpeg-cmd <path>.`);
+  }
+  const stderr = typeof r.stderr === "string" ? r.stderr : "";
+  if (r.status !== 0) {
+    throw new Error(`detect-scenes: ffmpeg failed on ${videoPath}.\n${stderr.slice(-600)}`);
+  }
+  const duration = parseFfmpegDuration(stderr);
+  const cuts = limitCuts(mergeCloseCuts(parseSceneCuts(stderr), minGap), opts.limit);
+  return {
+    video: videoPath,
+    threshold,
+    min_gap: minGap,
+    limit: opts.limit ?? null,
+    duration,
+    duration_us: duration === null ? null : Math.round(duration * US),
+    cuts: cuts.map((c) => ({
+      time: c.time,
+      time_us: Math.round(c.time * US),
+      timecode: timecode(c.time),
+      score: c.score,
+    })),
+    segments: buildSceneSegments(cuts, duration),
+  };
+}
diff --git a/test/detect-scenes.test.mjs b/test/detect-scenes.test.mjs
new file mode 100644
index 0000000..f3b448c
--- /dev/null
+++ b/test/detect-scenes.test.mjs
@@ -0,0 +1,242 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { after, describe, it } from "node:test";
+import {
+  buildSceneSegments,
+  limitCuts,
+  mergeCloseCuts,
+  parseFfmpegDuration,
+  parseSceneCuts,
+  timecode,
+} from "../dist/scenes.js";
+import { spawnCli } from "./helpers/spawn-cli.mjs";
+
+const US = 1_000_000;
+const hasFfmpeg = spawnSync("ffmpeg", ["-version"], { encoding: "utf-8" }).status === 0;
+
+// Three 1s solid-color scenes -> hard cuts at t=1 and t=2. Solid-color swaps
+// score exactly 0.4 on this ffmpeg, so tests pass an explicit --threshold 0.3
+// (the default 0.4 is a strict greater-than).
+function makeSceneClip(dir) {
+  const clip = join(dir, "scenes.mp4");
+  const src = (color) => ["-f", "lavfi", "-i", `color=c=${color}:size=160x120:rate=15:duration=1`];
+  const r = spawnSync(
+    "ffmpeg",
+    [
+      "-y",
+      "-loglevel",
+      "error",
+      ...src("red"),
+      ...src("blue"),
+      ...src("green"),
+      "-filter_complex",
+      "[0:v][1:v][2:v]concat=n=3:v=1:a=0,format=yuv420p[v]",
+      "-map",
+      "[v]",
+      clip,
+    ],
+    { encoding: "utf-8" },
+  );
+  assert.equal(r.status, 0, r.stderr);
+  return clip;
+}
+
+const METADATA_STDERR = [
+  "Input #0, mov,mp4,m4a,3gp,3g2,mj2, from 'scenes.mp4':",
+  "  Duration: 00:00:03.00, start: 0.000000, bitrate: 7 kb/s",
+  "[Parsed_metadata_1 @ 0x1] frame:0    pts:15360   pts_time:1",
+  "[Parsed_metadata_1 @ 0x1] lavfi.scene_score=0.400000",
+  "[Parsed_metadata_1 @ 0x1] frame:1    pts:30720   pts_time:2.5",
+  "[Parsed_metadata_1 @ 0x1] lavfi.scene_score=0.750000",
+].join("\n");
+
+describe("detect-scenes — parsing + cut math (pure)", () => {
+  it("pairs pts_time with the following scene_score", () => {
+    const cuts = parseSceneCuts(METADATA_STDERR);
+    assert.deepEqual(cuts, [
+      { time: 1, score: 0.4 },
+      { time: 2.5, score: 0.75 },
+    ]);
+  });
+
+  it("drops cuts at t<=0 and returns [] on unrelated stderr", () => {
+    const zero = "[Parsed_metadata_1 @ 0x1] frame:0 pts:0 pts_time:0\n[Parsed_metadata_1 @ 0x1] lavfi.scene_score=0.9";
+    assert.deepEqual(parseSceneCuts(zero), []);
+    assert.deepEqual(parseSceneCuts("Duration: 00:00:03.00\nnothing else"), []);
+  });
+
+  it("reads the input duration from the ffmpeg header", () => {
+    assert.equal(parseFfmpegDuration(METADATA_STDERR), 3);
+    assert.equal(parseFfmpegDuration("  Duration: 00:01:02.50, start: 0"), 62.5);
+    assert.equal(parseFfmpegDuration("no header here"), null);
+  });
+
+  it("mergeCloseCuts keeps the strongest cut of a close cluster", () => {
+    const cuts = [
+      { time: 1, score: 0.5 },
+      { time: 1.5, score: 0.8 },
+      { time: 4, score: 0.6 },
+    ];
+    assert.deepEqual(mergeCloseCuts(cuts, 2), [
+      { time: 1.5, score: 0.8 },
+      { time: 4, score: 0.6 },
+    ]);
+    // minGap 0 disables merging
+    assert.deepEqual(mergeCloseCuts(cuts, 0), cuts);
+    // ties keep the earliest cut
+    assert.deepEqual(
+      mergeCloseCuts(
+        [
+          { time: 1, score: 0.4 },
+          { time: 2, score: 0.4 },
+        ],
+        2,
+      ),
+      [{ time: 1, score: 0.4 }],
+    );
+  });
+
+  it("limitCuts keeps the N strongest, back in time order", () => {
+    const cuts = [
+      { time: 1, score: 0.5 },
+      { time: 5, score: 0.9 },
+      { time: 9, score: 0.7 },
+    ];
+    assert.deepEqual(limitCuts(cuts, 2), [
+      { time: 5, score: 0.9 },
+      { time: 9, score: 0.7 },
+    ]);
+    assert.deepEqual(limitCuts(cuts, undefined), cuts);
+  });
+
+  it("buildSceneSegments spans 0..duration and carries microseconds", () => {
+    const segments = buildSceneSegments(
+      [
+        { time: 1, score: 0.4 },
+        { time: 2.5, score: 0.75 },
+      ],
+      4,
+    );
+    assert.deepEqual(segments, [
+      { start: 0, end: 1, duration: 1, start_us: 0, end_us: US, duration_us: US },
+      { start: 1, end: 2.5, duration: 1.5, start_us: US, end_us: 2.5 * US, duration_us: 1.5 * US },
+      { start: 2.5, end: 4, duration: 1.5, start_us: 2.5 * US, end_us: 4 * US, duration_us: 1.5 * US },
+    ]);
+    // cuts at/after the known duration are dropped
+    assert.equal(buildSceneSegments([{ time: 5, score: 0.9 }], 4).length, 1);
+  });
+
+  it("buildSceneSegments leaves the tail open when duration is unknown", () => {
+    const segments = buildSceneSegments([{ time: 2, score: 0.5 }], null);
+    assert.equal(segments.length, 2);
+    assert.deepEqual(segments[1], {
+      start: 2,
+      end: null,
+      duration: null,
+      start_us: 2 * US,
+      end_us: null,
+      duration_us: null,
+    });
+  });
+
+  it("timecode formats hh:mm:ss.mmm", () => {
+    assert.equal(timecode(0), "00:00:00.000");
+    assert.equal(timecode(1.5), "00:00:01.500");
+    assert.equal(timecode(3723.042), "01:02:03.042");
+  });
+});
+
+describe("detect-scenes — CLI", () => {
+  function setup() {
+    const dir = mkdtempSync(join(tmpdir(), "capcut-detect-scenes-"));
+    return { dir, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
+  }
+
+  it("detects both hard cuts and returns draft-ready segments", { skip: !hasFfmpeg }, () => {
+    const s = setup();
+    after(s.cleanup);
+    const clip = makeSceneClip(s.dir);
+    const r = spawnCli(["detect-scenes", clip, "--threshold", "0.3", "--min-gap", "0.5"]);
+    assert.equal(r.status, 0, r.stderr);
+    assert.equal(r.json.cuts.length, 2, JSON.stringify(r.json.cuts));
+    assert.ok(Math.abs(r.json.cuts[0].time - 1) < 0.2, `cut 1 at ${r.json.cuts[0].time}`);
+    assert.ok(Math.abs(r.json.cuts[1].time - 2) < 0.2, `cut 2 at ${r.json.cuts[1].time}`);
+    assert.match(r.json.cuts[0].timecode, /^00:00:0\d\.\d{3}$/);
+    assert.ok(Math.abs(r.json.duration - 3) < 0.2);
+    assert.equal(r.json.segments.length, 3);
+    assert.equal(r.json.segments[0].start, 0);
+    for (const seg of r.json.segments) {
+      assert.equal(seg.start_us, Math.round(seg.start * US));
+      assert.equal(seg.end_us, Math.round(seg.end * US));
+      assert.equal(seg.duration_us, seg.end_us - seg.start_us);
+    }
+    // segments tile the clip: each start = previous end
+    assert.equal(r.json.segments[1].start, r.json.segments[0].end);
+    assert.equal(r.json.segments[2].start, r.json.segments[1].end);
+  });
+
+  it("--min-gap merges cuts closer than the gap (default 2s)", { skip: !hasFfmpeg }, () => {
+    const s = setup();
+    after(s.cleanup);
+    const clip = makeSceneClip(s.dir);
+    const r = spawnCli(["detect-scenes", clip, "--threshold", "0.3"]);
+    assert.equal(r.status, 0, r.stderr);
+    // cuts at ~1s and ~2s are 1s apart -> merged into one under the 2s default
+    assert.equal(r.json.cuts.length, 1);
+    assert.equal(r.json.segments.length, 2);
+  });
+
+  it("--limit keeps only the N strongest cuts", { skip: !hasFfmpeg }, () => {
+    const s = setup();
+    after(s.cleanup);
+    const clip = makeSceneClip(s.dir);
+    const r = spawnCli(["detect-scenes", clip, "--threshold", "0.3", "--min-gap", "0.5", "--limit", "1"]);
+    assert.equal(r.status, 0, r.stderr);
+    assert.equal(r.json.cuts.length, 1);
+    assert.equal(r.json.segments.length, 2);
+  });
+
+  it("-H prints a human summary; --json overrides it", { skip: !hasFfmpeg }, () => {
+    const s = setup();
+    after(s.cleanup);
+    const clip = makeSceneClip(s.dir);
+    const human = spawnCli(["detect-scenes", clip, "--threshold", "0.3", "-H"]);
+    assert.equal(human.status, 0, human.stderr);
+    assert.equal(human.json, null, "human output must not be JSON");
+    assert.match(human.stdout, /Cuts:\s+1/);
+    assert.match(human.stdout, /00:00:0\d\.\d{3}/);
+    const json = spawnCli(["detect-scenes", clip, "--threshold", "0.3", "-H", "--json"]);
+    assert.equal(json.status, 0, json.stderr);
+    assert.ok(json.json && Array.isArray(json.json.cuts), "--json must force JSON output");
+  });
+
+  it("fails with a clear error when the video is missing", () => {
+    const r = spawnCli(["detect-scenes", "/nonexistent/video.mp4"]);
+    assert.equal(r.status, 1);
+    assert.match(r.stderr, /video not found/);
+  });
+
+  it("fails actionably when ffmpeg is unavailable", () => {
+    const s = setup();
+    after(s.cleanup);
+    const placeholder = join(s.dir, "clip.mp4");
+    writeFileSync(placeholder, "");
+    const r = spawnCli(["detect-scenes", placeholder, "--ffmpeg-cmd", "/nonexistent/ffmpeg"]);
+    assert.equal(r.status, 1);
+    assert.match(r.stderr, /ffmpeg is unavailable/);
+    assert.match(r.stderr, /--ffmpeg-cmd/);
+  });
+
+  it("rejects an out-of-range threshold", () => {
+    const s = setup();
+    after(s.cleanup);
+    const placeholder = join(s.dir, "clip.mp4");
+    writeFileSync(placeholder, "");
+    const r = spawnCli(["detect-scenes", placeholder, "--threshold", "1.5"]);
+    assert.equal(r.status, 1);
+    assert.match(r.stderr, /--threshold must be in/);
+  });
+});

From 7b648949170e1f44eb7b25249650968893aae4cd Mon Sep 17 00:00:00 2001
From: Rene Zander <renezander030@gmail.com>
Date: Wed, 8 Jul 2026 07:57:41 +0000
Subject: [PATCH 06/17] feat(preset): make-preset extracts a reusable
 text-style preset; apply via --preset

Power users hand-tune caption styling once and want to reuse it across
drafts. 'capcut make-preset <project> <text-segment-id> --out <preset.json>'
extracts a text segment's full re-appliable styling into a versioned,
portable JSON ({"capcutCliPreset": 1}): font identity (name/path/resource
id), fill/stroke/background colors, style flags, alignment + position
transform, bubble reference, and per-range karaoke styling when present.

Apply side: --preset <file> on add-text and text-style (material fields +
content styles[0] + transform + bubble + text ranges) and on caption (base
cue style, same coverage as --style-ref). Explicit CLI flags always
override preset values; a wrong or missing schema fails with a clear
validation error. Only properties the CLI can already re-apply are
captured (factory STYLE_FIELDS + TextStyleOptions + add-text options);
animations are excluded because they attach via enum slugs and
segment-relative timings that don't survive a portable preset.

Prior art: Davidb-2107/capcut-cli-david v1.14.0 (make-preset --out /
restyle --preset flag semantics), implemented natively on upstream's
save-template/apply-template pattern. Ecosystem asks:
GuanYixuan/pyJianYingDraft#192 (cannot programmatically set fonts),
Hommy-master/capcut-mate#57 (custom fonts require code edits).
---
 src/caption.ts            |  11 +-
 src/command-specs.ts      |  15 ++-
 src/factory.ts            |   5 +-
 src/index.ts              |  68 +++++++++-
 src/preset.ts             | 264 ++++++++++++++++++++++++++++++++++++++
 test/make-preset.test.mjs | 249 +++++++++++++++++++++++++++++++++++
 6 files changed, 603 insertions(+), 9 deletions(-)
 create mode 100644 src/preset.ts
 create mode 100644 test/make-preset.test.mjs

diff --git a/src/caption.ts b/src/caption.ts
index 2b04b49..43450b8 100644
--- a/src/caption.ts
+++ b/src/caption.ts
@@ -6,6 +6,7 @@ import { join } from "node:path";
 import { setTextRanges } from "./decorators.js";
 import type { Draft, Segment, Track } from "./draft.js";
 import { findSegment } from "./draft.js";
+import { captionStyleFromPreset, type TextStylePreset } from "./preset.js";
 import { parseSrt } from "./srt.js";
 
 export interface CaptionOptions {
@@ -16,6 +17,7 @@ export interface CaptionOptions {
   language?: string; // ISO code; default "auto"
   trackName?: string; // default "captions"
   styleRef?: string; // segment ID whose styling to copy
+  preset?: TextStylePreset; // make-preset file whose base style to apply
   whisperEngine?: "auto" | "openai" | "whisper-cpp" | "faster-whisper";
   karaoke?: boolean;
   maxWords?: number;
@@ -65,6 +67,9 @@ export interface CaptionResult {
  *   4. Create captions track + real subtitle material per cue
  */
 export function captionDraft(draft: Draft, opts: CaptionOptions): CaptionResult {
+  if (opts.styleRef && opts.preset) {
+    throw new Error("--style-ref and --preset are mutually exclusive. Pass one style source.");
+  }
   const audio = resolveAudio(draft, opts);
   const transcription = runWhisper(audio, opts);
   const cues = opts.karaoke
@@ -81,7 +86,11 @@ export function captionDraft(draft: Draft, opts: CaptionOptions): CaptionResult
 
   const trackName = opts.trackName ?? "captions";
   const styleSource = opts.styleRef ? findSegment(draft, opts.styleRef) : null;
-  const baseStyle = styleSource ? extractTextStyle(draft, styleSource.segment.material_id) : defaultCaptionStyle();
+  const baseStyle = styleSource
+    ? extractTextStyle(draft, styleSource.segment.material_id)
+    : opts.preset
+      ? captionStyleFromPreset(opts.preset)
+      : defaultCaptionStyle();
 
   let track = draft.tracks.find((t) => t.type === "text" && t.name === trackName);
   if (!track) {
diff --git a/src/command-specs.ts b/src/command-specs.ts
index aadc1ef..ced6ef1 100644
--- a/src/command-specs.ts
+++ b/src/command-specs.ts
@@ -89,6 +89,12 @@ const TRACK_NAME = option("track_name", ["--track-name"], "string", "Target trac
 const OUT = option("out", ["--out"], "path", "Output path.");
 const FFPROBE = option("ffprobe_cmd", ["--ffprobe-cmd"], "path", "ffprobe binary.");
 const STYLE_REF = option("style_ref", ["--style-ref"], "id", "Copy styling from this text segment.");
+const PRESET = option(
+  "preset",
+  ["--preset"],
+  "path",
+  "Apply a make-preset style preset; explicit flags override preset values.",
+);
 const TEXT_STYLE: OptionSpec[] = [
   option("font_size", ["--font-size"], "number", "Font size."),
   option("color", ["--color"], "string", "Text colour as #RRGGBB."),
@@ -156,6 +162,7 @@ const usages = {
   "add-effect": "capcut add-effect <project> <slug> <start> <duration> [options]",
   "save-template": "capcut save-template <project> <id> <name> --out <path>",
   "apply-template": "capcut apply-template <project> <template> <start> <duration> [text] [options]",
+  "make-preset": "capcut make-preset <project> <text-segment-id> --out <preset.json>",
   batch: "capcut batch <project> [--continue-on-error] < operations.jsonl",
   "import-srt": "capcut import-srt <project> <srt-or-> [options]",
   "import-ass": "capcut import-ass <project> <ass-or-> [options]",
@@ -220,7 +227,7 @@ const optionsByCommand: Record<string, OptionSpec[]> = {
     option("no_probe", ["--no-probe"], "boolean", "Disable automatic media probing."),
     FFPROBE,
   ],
-  "add-text": [TRACK_NAME, ...TEXT_STYLE.slice(0, 5)],
+  "add-text": [TRACK_NAME, ...TEXT_STYLE.slice(0, 5), PRESET],
   cut: [OUT],
   keyframe: [option("batch", ["--batch"], "boolean", "Read JSONL keyframes from stdin.")],
   transition: [option("duration", ["--duration"], "time", "Transition duration.")],
@@ -236,7 +243,7 @@ const optionsByCommand: Record<string, OptionSpec[]> = {
     option("round_corner", ["--round-corner"], "number", "Rectangle corner radius."),
   ],
   "bg-blur": [option("off", ["--off"], "boolean", "Remove background blur.")],
-  "text-style": TEXT_STYLE,
+  "text-style": [...TEXT_STYLE, PRESET],
   "text-anim": [
     option("intro", ["--intro"], "enum", "Intro animation."),
     option("outro", ["--outro"], "enum", "Outro animation."),
@@ -266,6 +273,7 @@ const optionsByCommand: Record<string, OptionSpec[]> = {
   ],
   "add-effect": [TRACK_NAME, option("params", ["--params"], "json", "Effect parameter array.")],
   "save-template": [OUT],
+  "make-preset": [OUT],
   "apply-template": [
     option("x", ["--x"], "number", "Horizontal position override."),
     option("y", ["--y"], "number", "Vertical position override."),
@@ -305,6 +313,7 @@ const optionsByCommand: Record<string, OptionSpec[]> = {
     option("max_gap_ms", ["--max-gap-ms"], "number", "Maximum gap inside a karaoke cue."),
     TRACK_NAME,
     STYLE_REF,
+    PRESET,
   ],
   translate: [
     option("to", ["--to"], "string", "Target language."),
@@ -436,7 +445,7 @@ const mutating = new Set([
 
 const arrayOutputs = new Set(["tracks", "segments", "texts", "materials", "enums", "templates"]);
 const textOutputs = new Set(["export-srt", "completions"]);
-const fileOutputs = new Set(["render", "translate", "compile", "cut", "save-template"]);
+const fileOutputs = new Set(["render", "translate", "compile", "cut", "save-template", "make-preset"]);
 
 function inferType(name: string): ArgumentType {
   if (/project|file|path|dir|template|audio|image|srt|ass|spec|draft/i.test(name)) return "path";
diff --git a/src/factory.ts b/src/factory.ts
index 35f5b00..131abd2 100644
--- a/src/factory.ts
+++ b/src/factory.ts
@@ -425,8 +425,9 @@ function buildTextContent(text: string, fontSize: number, color: [number, number
 }
 
 // Fields on a text material that describe *styling* (not content or timing).
-// Used by import-srt --style-ref to mirror an existing caption's look.
-const STYLE_FIELDS = [
+// Used by import-srt --style-ref to mirror an existing caption's look, and by
+// make-preset (src/preset.ts) as the set of material fields a preset carries.
+export const STYLE_FIELDS = [
   "alignment",
   "font_size",
   "text_color",
diff --git a/src/index.ts b/src/index.ts
index 6199323..deaf948 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -82,6 +82,7 @@ import {
 import { sanitizeDraftBundle } from "./fixture.js";
 import { DEFAULT_LINT_OPTIONS, fixDraft, type LintOptions, lintDraft, lintExitCode, summarize } from "./lint.js";
 import { migrateDraft } from "./migrate.js";
+import { applyTextPreset, extractTextPreset, loadPresetFile, type TextStylePreset } from "./preset.js";
 import { probeMedia } from "./probe.js";
 import { runQuickstart } from "./quickstart.js";
 import { buildRenderPlan, renderDraft } from "./render.js";
@@ -132,6 +133,7 @@ export const COMMANDS = [
   "add-effect",
   "save-template",
   "apply-template",
+  "make-preset",
   "templates",
   "batch",
   "import-srt",
@@ -264,6 +266,8 @@ Add:
                --align <0|1|2>    Left/center/right (default: 1)
                --x <n> --y <n>    Position (-1 to 1, default: 0,0)
                --track-name <s>   Track name (default: "text")
+               --preset <file>    Apply a make-preset style preset; explicit
+                                  flags override preset values
 
 Edit:
   set-text   <project> <id> <text>              Change text content
@@ -324,6 +328,8 @@ Animate:
                --border-width --border-color --border-alpha
                --bg-color --bg-alpha --bg-style --bg-round-radius
                --bg-width --bg-height --bg-h-offset --bg-v-offset
+               --preset <file>  Apply a make-preset style preset; explicit
+                                flags override preset values
   text-ranges <project> <id> --styles @path.json  |  --styles '<inline-json>'
              Multi-colour text — write multiple styles to one text segment.
              JSON array of { "start": int, "end": int,
@@ -392,7 +398,13 @@ Templates:
   apply-template <project> <template.json> <start> <duration> [text override]
              Stamp a template into a project at the given time
              Options: --x <n> --y <n> (override position)
-  templates  
+  make-preset <project> <text-segment-id> --out <preset.json>
+             Extract the text styling of a segment as a reusable preset
+             (font, colors, shadow/border/background box, alignment/position,
+             bubble, text ranges). Apply with --preset on add-text,
+             text-style, or caption; explicit CLI flags override preset
+             values.
+  templates
              Show available templates in the template library.
              Use -H for a table.
 
@@ -418,6 +430,8 @@ Caption (v0.4 — real subtitle objects, fixes import-srt mimicry):
                --language <code>    ISO code or "auto" (default)
                --track-name <s>     Caption track name (default: "captions")
                --style-ref <seg-id> Mirror styling from existing text segment
+               --preset <file>      Base style from a make-preset file
+                                    (same coverage as --style-ref)
 
 Translate (v0.4 — multi-language draft clone):
   translate  <project> --to <lang> --out <path> [options]
@@ -572,6 +586,8 @@ interface Flags {
   font?: string;
   // text-ranges
   styles?: string;
+  // make-preset / --preset
+  preset?: string;
   // wikimedia
   forceLicense?: boolean;
   // lint
@@ -835,6 +851,8 @@ function parseFlags(args: string[]): { positional: string[]; flags: Flags } {
       flags.jianying = true;
     } else if (a === "--styles" && i + 1 < args.length) {
       flags.styles = args[++i];
+    } else if (a === "--preset" && i + 1 < args.length) {
+      flags.preset = args[++i];
     } else if (a === "--force-license") {
       flags.forceLicense = true;
     } else if (a === "--max-chars" && i + 1 < args.length) {
@@ -1455,11 +1473,26 @@ async function cmdAddVideo(draft: Draft, filePath: string, positional: string[],
   out(payload, flags);
 }
 
+// Explicit CLI flags beat preset values: stamp the flag values over a clone of
+// the preset before applying, so the apply step is the single writer.
+function presetWithFlagOverrides(preset: TextStylePreset, flags: Flags): TextStylePreset {
+  const p = structuredClone(preset);
+  if (flags.fontSize !== undefined) p.style.font_size = flags.fontSize;
+  if (flags.color !== undefined) p.style.text_color = flags.color;
+  if (flags.align !== undefined) p.style.alignment = flags.align;
+  if (p.transform) {
+    if (flags.x !== undefined) p.transform.x = flags.x;
+    if (flags.y !== undefined) p.transform.y = flags.y;
+  }
+  return p;
+}
+
 function cmdAddText(draft: Draft, filePath: string, positional: string[], flags: Flags): void {
   const startStr = positional[2];
   const durationStr = positional[3];
   const text = positional.slice(4).join(" ");
   if (!text) die("Missing text. Usage: capcut add-text <project> <start> <duration> <text>");
+  const preset = flags.preset ? loadPresetFile(flags.preset) : null;
   const start = parseTimeInput(startStr);
   const duration = parseTimeInput(durationStr);
   const opts: AddTextOptions = {
@@ -1474,6 +1507,7 @@ function cmdAddText(draft: Draft, filePath: string, positional: string[], flags:
     trackName: flags.trackName,
   };
   const result = addText(draft, filePath, opts);
+  if (preset) applyTextPreset(draft, result.segmentId, presetWithFlagOverrides(preset, flags));
   saveDraft(filePath, draft);
   out(
     {
@@ -1484,6 +1518,7 @@ function cmdAddText(draft: Draft, filePath: string, positional: string[], flags:
       text,
       start_us: start,
       duration_us: duration,
+      ...(flags.preset ? { preset: flags.preset } : {}),
     },
     flags,
   );
@@ -1618,10 +1653,20 @@ function cmdTextStyle(draft: Draft, filePath: string, positional: string[], flag
     bgHOffset: flags.bgHOffset,
     bgVOffset: flags.bgVOffset,
   };
+  const applied: string[] = [];
+  let materialId = "";
+  if (flags.preset) {
+    const presetResult = applyTextPreset(draft, segId, loadPresetFile(flags.preset));
+    materialId = presetResult.materialId;
+    applied.push(...presetResult.applied);
+  }
+  // Explicit flags run after the preset so they override its values.
   const result = setTextStyle(draft, segId, opts);
-  if (result.applied.length === 0) die(`No styling flags provided. See 'capcut --help'.`);
+  materialId = result.materialId;
+  applied.push(...result.applied);
+  if (applied.length === 0) die(`No styling flags provided. See 'capcut --help'.`);
   saveDraft(filePath, draft);
-  out({ ok: true, id: segId, material_id: result.materialId, applied: result.applied }, flags);
+  out({ ok: true, id: segId, material_id: materialId, applied }, flags);
 }
 
 function cmdTextAnim(draft: Draft, filePath: string, positional: string[], flags: Flags): void {
@@ -1839,6 +1884,17 @@ function cmdApplyTemplate(draft: Draft, filePath: string, positional: string[],
   );
 }
 
+// Read-only sibling of save-template: extracts a text segment's styling as a
+// portable preset JSON for --preset on add-text / text-style / caption.
+function cmdMakePreset(draft: Draft, positional: string[], flags: Flags): void {
+  const segId = positional[2];
+  if (!flags.out)
+    die("Missing --out <path>. Usage: capcut make-preset <project> <text-segment-id> --out <preset.json>");
+  const { preset, segmentId, materialId, captured } = extractTextPreset(draft, segId);
+  writeFileSync(flags.out, JSON.stringify(preset, null, 2), "utf-8");
+  out({ ok: true, segment_id: segmentId, material_id: materialId, captured, out: flags.out }, flags);
+}
+
 // --- Phase 4: multi-style text ranges ---
 
 function cmdTextRanges(draft: Draft, filePath: string, positional: string[], flags: Flags): void {
@@ -2099,6 +2155,7 @@ function cmdCaption(draft: Draft, filePath: string, flags: Flags): void {
     language: flags.language,
     trackName: flags.trackName,
     styleRef: flags.styleRef,
+    preset: flags.preset ? loadPresetFile(flags.preset) : undefined,
     karaoke: flags.karaoke,
     maxWords: flags.maxWords,
     maxChars: flags.maxChars,
@@ -2680,6 +2737,7 @@ const SUMMARIES: Record<string, string> = {
   "add-effect": "Add a scene effect on its own track.",
   "save-template": "Extract a segment as a reusable template JSON.",
   "apply-template": "Stamp a template into a project with new timing/text.",
+  "make-preset": "Extract a text segment's styling as a reusable preset JSON (apply via --preset).",
   templates: "List bundled reusable templates.",
   batch: "Run multiple edits from stdin (JSONL), one file write.",
   "import-srt": "Import an SRT file/stdin as one text segment per cue.",
@@ -3365,6 +3423,10 @@ async function main(): Promise<void> {
       requireArgs(positional, 5, "capcut apply-template <project> <template.json> <start> <duration>");
       cmdApplyTemplate(draft, filePath, positional, flags);
       break;
+    case "make-preset":
+      requireArgs(positional, 3, "capcut make-preset <project> <text-segment-id> --out <preset.json>");
+      cmdMakePreset(draft, positional, flags);
+      break;
     case "batch":
       cmdBatch(draft, filePath, flags);
       break;
diff --git a/src/preset.ts b/src/preset.ts
new file mode 100644
index 0000000..e49b577
--- /dev/null
+++ b/src/preset.ts
@@ -0,0 +1,264 @@
+import { readFileSync } from "node:fs";
+import { setBubble, setTextRanges, type TextRangeInput } from "./decorators.js";
+import type { Draft, MaterialText } from "./draft.js";
+import { findMaterial, findSegment } from "./draft.js";
+import { STYLE_FIELDS } from "./factory.js";
+
+// --- Text style presets (make-preset / --preset) ---
+// A preset captures the styling of one text segment as a portable JSON file:
+// the STYLE_FIELDS material fields (font identity, colors, shadow/border/
+// background box, alignment, spacing), the content styles[0] flags, the clip
+// transform, the bubble reference, and per-range styles (karaoke highlights).
+// Only properties the CLI can re-apply are captured — animations are excluded
+// because they attach via enum slugs and segment-relative timings that don't
+// survive a portable preset. Fork prior art: Davidb-2107/capcut-cli-david
+// v1.14.0 (make-preset --out / restyle --preset).
+
+export const PRESET_VERSION = 1;
+
+export interface TextStylePreset {
+  capcutCliPreset: number;
+  style: Record<string, unknown>;
+  transform?: { x: number; y: number };
+  bubble?: { effect_id: string; resource_id: string };
+  text_ranges?: TextRangeInput[];
+}
+
+function hexToRgb01(hex: string): [number, number, number] {
+  const h = hex.replace("#", "");
+  return [parseInt(h.slice(0, 2), 16) / 255, parseInt(h.slice(2, 4), 16) / 255, parseInt(h.slice(4, 6), 16) / 255];
+}
+
+function rgb01ToHex(rgb: [number, number, number]): string {
+  const channel = (v: number) =>
+    Math.round(Math.min(1, Math.max(0, v)) * 255)
+      .toString(16)
+      .padStart(2, "0");
+  return `#${channel(rgb[0])}${channel(rgb[1])}${channel(rgb[2])}`.toUpperCase();
+}
+
+interface ContentStyleBlock {
+  range?: [number, number];
+  size?: number;
+  bold?: boolean;
+  italic?: boolean;
+  underline?: boolean;
+  fill?: {
+    alpha?: number;
+    content?: { render_type?: string; solid?: { color?: [number, number, number]; alpha?: number } };
+  };
+  font?: { id?: string; path?: string };
+  [key: string]: unknown;
+}
+
+function parseContent(mat: MaterialText): { styles?: ContentStyleBlock[]; text?: string } | null {
+  try {
+    return JSON.parse(mat.content) as { styles?: ContentStyleBlock[]; text?: string };
+  } catch {
+    return null;
+  }
+}
+
+export function extractTextPreset(
+  draft: Draft,
+  segmentId: string,
+): { preset: TextStylePreset; segmentId: string; materialId: string; captured: string[] } {
+  const found = findSegment(draft, segmentId);
+  if (!found) throw new Error(`Segment not found: ${segmentId}`);
+  if (found.track.type !== "text") {
+    throw new Error(`make-preset only applies to text segments (track type: ${found.track.type})`);
+  }
+  const seg = found.segment;
+  const mat = findMaterial(draft.materials.texts, seg.material_id);
+  if (!mat) throw new Error(`Text material not found for segment ${segmentId}`);
+
+  const m = mat as unknown as Record<string, unknown>;
+  const style: Record<string, unknown> = {};
+  for (const f of STYLE_FIELDS) {
+    if (m[f] !== undefined) style[f] = m[f];
+  }
+
+  // Fill gaps from the content's base style block — CapCut renders from there,
+  // and add-text only stamps some of these at the material level.
+  const content = parseContent(mat);
+  const base = content?.styles?.[0];
+  if (base) {
+    if (style.font_size === undefined && base.size !== undefined) style.font_size = base.size;
+    if (style.bold === undefined && base.bold !== undefined) style.bold = base.bold;
+    if (style.italic === undefined && base.italic !== undefined) style.italic = base.italic;
+    if (style.underline === undefined && base.underline !== undefined) style.underline = base.underline;
+    const solid = base.fill?.content?.solid;
+    if (style.text_color === undefined && solid?.color) style.text_color = rgb01ToHex(solid.color);
+    if (style.font_path === undefined && base.font?.path) style.font_path = base.font.path;
+    if (style.font_id === undefined && base.font?.id) style.font_id = base.font.id;
+  }
+
+  const preset: TextStylePreset = { capcutCliPreset: PRESET_VERSION, style };
+  const captured = ["style"];
+
+  if (seg.clip?.transform) {
+    preset.transform = { x: seg.clip.transform.x, y: seg.clip.transform.y };
+    captured.push("transform");
+  }
+
+  if (typeof m.bubble_effect_id === "string" && m.bubble_effect_id && typeof m.bubble_resource_id === "string") {
+    preset.bubble = { effect_id: m.bubble_effect_id, resource_id: m.bubble_resource_id };
+    captured.push("bubble");
+  }
+
+  // Multi-range styling (text-ranges / karaoke). Ranges are stored in UTF-16LE
+  // bytes; convert back to code units (BMP assumption, same as setTextRanges).
+  const styles = content?.styles ?? [];
+  if (styles.length > 1) {
+    const ranges: TextRangeInput[] = [];
+    for (const s of styles) {
+      if (!Array.isArray(s.range) || s.range.length !== 2) continue;
+      const solid = s.fill?.content?.solid;
+      ranges.push({
+        start: s.range[0] / 2,
+        end: s.range[1] / 2,
+        font_color: solid?.color ? rgb01ToHex(solid.color) : undefined,
+        font_size: s.size,
+        font_alpha: solid?.alpha,
+        bold: s.bold,
+        italic: s.italic,
+        underline: s.underline,
+      });
+    }
+    if (ranges.length > 0) {
+      preset.text_ranges = ranges;
+      captured.push("text_ranges");
+    }
+  }
+
+  return { preset, segmentId: seg.id, materialId: mat.id, captured };
+}
+
+export function parsePreset(raw: string, source: string): TextStylePreset {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    throw new Error(`Preset is not valid JSON: ${e instanceof Error ? e.message : String(e)} (${source})`);
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`Preset must be a JSON object: ${source}`);
+  }
+  const p = parsed as Record<string, unknown>;
+  if (p.capcutCliPreset === undefined) {
+    throw new Error(
+      `Not a capcut-cli preset (missing "capcutCliPreset" marker): ${source}. Generate one with 'capcut make-preset'.`,
+    );
+  }
+  if (p.capcutCliPreset !== PRESET_VERSION) {
+    throw new Error(`Unsupported preset version: ${String(p.capcutCliPreset)} (this CLI supports ${PRESET_VERSION})`);
+  }
+  if (p.style === null || typeof p.style !== "object" || Array.isArray(p.style)) {
+    throw new Error(`Preset "style" must be an object: ${source}`);
+  }
+  return p as unknown as TextStylePreset;
+}
+
+export function loadPresetFile(path: string): TextStylePreset {
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf-8");
+  } catch {
+    throw new Error(`Preset file not found: ${path}`);
+  }
+  return parsePreset(raw, path);
+}
+
+export function applyTextPreset(
+  draft: Draft,
+  segmentId: string,
+  preset: TextStylePreset,
+): { materialId: string; applied: string[] } {
+  const found = findSegment(draft, segmentId);
+  if (!found) throw new Error(`Segment not found: ${segmentId}`);
+  if (found.track.type !== "text") {
+    throw new Error(`--preset only applies to text segments (track type: ${found.track.type})`);
+  }
+  const seg = found.segment;
+  const mat = findMaterial(draft.materials.texts, seg.material_id);
+  if (!mat) throw new Error(`Text material not found for segment ${segmentId}`);
+
+  const m = mat as unknown as Record<string, unknown>;
+  const applied: string[] = [];
+  for (const f of STYLE_FIELDS) {
+    if (preset.style[f] !== undefined) m[f] = preset.style[f];
+  }
+  applied.push("style");
+
+  // Mirror the base style into `content`'s styles[0] — CapCut renders from
+  // there. Preserve the segment's own text and range.
+  const content = parseContent(mat);
+  const base = content?.styles?.[0];
+  if (content && base) {
+    if (typeof preset.style.font_size === "number") base.size = preset.style.font_size;
+    if (typeof preset.style.bold === "boolean") base.bold = preset.style.bold;
+    if (typeof preset.style.italic === "boolean") base.italic = preset.style.italic;
+    if (typeof preset.style.underline === "boolean") base.underline = preset.style.underline;
+    if (typeof preset.style.text_color === "string") {
+      base.fill = {
+        alpha: 1,
+        content: { render_type: "solid", solid: { alpha: 1, color: hexToRgb01(preset.style.text_color) } },
+      };
+    }
+    if (typeof preset.style.font_path === "string") {
+      base.font = {
+        id: typeof preset.style.font_id === "string" ? preset.style.font_id : "",
+        path: preset.style.font_path,
+      };
+    }
+    mat.content = JSON.stringify(content);
+  }
+
+  if (preset.transform && seg.clip) {
+    seg.clip.transform = { x: preset.transform.x, y: preset.transform.y };
+    applied.push("transform");
+  }
+
+  if (preset.bubble) {
+    setBubble(draft, seg.id, { effectId: preset.bubble.effect_id, resourceId: preset.bubble.resource_id });
+    applied.push("bubble");
+  }
+
+  if (preset.text_ranges && preset.text_ranges.length > 0) {
+    // Ranges came from a different text; keep the ones that fit this one.
+    const textLength = (parseContent(mat)?.text ?? "").length;
+    const ranges = preset.text_ranges
+      .map((r) => ({ ...r, end: Math.min(r.end, textLength) }))
+      .filter((r) => r.start < r.end);
+    if (ranges.length > 0) {
+      setTextRanges(draft, seg.id, ranges);
+      applied.push("text_ranges");
+    }
+  }
+
+  return { materialId: mat.id, applied };
+}
+
+// Base style block for caption cues — same coverage as caption --style-ref
+// (content styles[0] plus the font_size/font_color fields the caption
+// material reads), so --preset slots into the existing baseStyle path.
+export function captionStyleFromPreset(preset: TextStylePreset): Record<string, unknown> {
+  const color = typeof preset.style.text_color === "string" ? preset.style.text_color : "#FFFFFF";
+  const size = typeof preset.style.font_size === "number" ? preset.style.font_size : 15;
+  const block: Record<string, unknown> = {
+    font_color: color,
+    font_size: size,
+    size,
+    bold: preset.style.bold ?? false,
+    italic: preset.style.italic ?? false,
+    underline: preset.style.underline ?? false,
+    fill: { alpha: 1, content: { render_type: "solid", solid: { alpha: 1, color: hexToRgb01(color) } } },
+  };
+  if (typeof preset.style.font_path === "string") {
+    block.font = {
+      id: typeof preset.style.font_id === "string" ? preset.style.font_id : "",
+      path: preset.style.font_path,
+    };
+  }
+  return block;
+}
diff --git a/test/make-preset.test.mjs b/test/make-preset.test.mjs
new file mode 100644
index 0000000..18d0f0d
--- /dev/null
+++ b/test/make-preset.test.mjs
@@ -0,0 +1,249 @@
+import assert from "node:assert/strict";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { after, describe, it } from "node:test";
+import { loadDraft } from "./helpers/load-fixture.mjs";
+import { spawnCli } from "./helpers/spawn-cli.mjs";
+import { tmpDir, tmpDraft } from "./helpers/tmp-draft.mjs";
+
+describe("capcut make-preset + add-text --preset roundtrip", () => {
+  const src = tmpDraft();
+  const out = tmpDir();
+  after(() => {
+    src.cleanup();
+    out.cleanup();
+  });
+
+  it("styling extracted from a segment recreates itself in a fresh draft", () => {
+    // 1. Style a text segment through CLI flags only.
+    const added = spawnCli([
+      "add-text",
+      src.path,
+      "1s",
+      "3s",
+      "styled caption",
+      "--font-size",
+      "24",
+      "--color",
+      "#FF3300",
+      "--align",
+      "2",
+      "--x",
+      "0.1",
+      "--y",
+      "-0.55",
+    ]);
+    assert.equal(added.status, 0, `stderr: ${added.stderr}`);
+    const segId = added.json.segment_id;
+    const styled = spawnCli([
+      "text-style",
+      src.path,
+      segId,
+      "--alpha",
+      "0.9",
+      "--shadow",
+      "--shadow-color",
+      "#00FF00",
+      "--shadow-distance",
+      "8",
+      "--border-width",
+      "20",
+      "--border-color",
+      "#0000FF",
+      "--bg-color",
+      "#112233",
+      "--bg-alpha",
+      "0.8",
+    ]);
+    assert.equal(styled.status, 0, `stderr: ${styled.stderr}`);
+    const bubbled = spawnCli(["bubble-text", src.path, segId, "--bubble", "cloud"]);
+    assert.equal(bubbled.status, 0, `stderr: ${bubbled.stderr}`);
+
+    // 2. Extract the preset.
+    const presetPath = join(out.dir, "style.json");
+    const made = spawnCli(["make-preset", src.path, segId, "--out", presetPath]);
+    assert.equal(made.status, 0, `stderr: ${made.stderr}`);
+    assert.equal(made.json.ok, true);
+    assert.ok(existsSync(presetPath));
+    const preset = JSON.parse(readFileSync(presetPath, "utf-8"));
+    assert.equal(preset.capcutCliPreset, 1);
+    assert.equal(preset.style.font_size, 24);
+    assert.equal(preset.style.text_color, "#FF3300");
+    assert.equal(preset.style.shadow_color, "#00FF00");
+    assert.deepEqual(preset.transform, { x: 0.1, y: -0.55 });
+    assert.equal(preset.bubble.effect_id, "7137269184932778510");
+
+    // 3. Apply into a fresh draft, then re-extract: a true roundtrip.
+    const dst = tmpDraft();
+    try {
+      const applied = spawnCli(["add-text", dst.path, "0s", "2s", "new text", "--preset", presetPath]);
+      assert.equal(applied.status, 0, `stderr: ${applied.stderr}`);
+      assert.equal(applied.json.ok, true);
+
+      const roundtripPath = join(out.dir, "roundtrip.json");
+      const remade = spawnCli(["make-preset", dst.path, applied.json.segment_id, "--out", roundtripPath]);
+      assert.equal(remade.status, 0, `stderr: ${remade.stderr}`);
+      assert.deepEqual(JSON.parse(readFileSync(roundtripPath, "utf-8")), preset);
+
+      // The styling landed on the draft itself, not just the preset file.
+      const draft = loadDraft(dst.path);
+      const mat = draft.materials.texts.find((t) => t.id === applied.json.material_id);
+      assert.equal(mat.text_color, "#FF3300");
+      assert.equal(mat.font_size, 24);
+      assert.equal(mat.shadow_color, "#00FF00");
+      assert.equal(mat.border_width, 20);
+      assert.equal(mat.background_color, "#112233");
+      assert.equal(mat.bubble_effect_id, "7137269184932778510");
+      const content = JSON.parse(mat.content);
+      assert.equal(content.text, "new text");
+      assert.equal(content.styles[0].size, 24);
+    } finally {
+      dst.cleanup();
+    }
+  });
+});
+
+describe("--preset precedence and validation", () => {
+  const fix = tmpDraft();
+  const out = tmpDir();
+  const presetPath = join(out.dir, "preset.json");
+  writeFileSync(
+    presetPath,
+    JSON.stringify({
+      capcutCliPreset: 1,
+      style: {
+        font_size: 24,
+        text_color: "#FF3300",
+        has_border: true,
+        border_width: 20,
+        border_color: "#0000FF",
+        border_alpha: 1,
+      },
+      transform: { x: 0.1, y: -0.55 },
+    }),
+  );
+  after(() => {
+    fix.cleanup();
+    out.cleanup();
+  });
+
+  it("add-text: explicit flags beat preset values", () => {
+    const r = spawnCli([
+      "add-text",
+      fix.path,
+      "0s",
+      "2s",
+      "flag wins",
+      "--preset",
+      presetPath,
+      "--color",
+      "#00CCFF",
+      "--y",
+      "0.3",
+    ]);
+    assert.equal(r.status, 0, `stderr: ${r.stderr}`);
+    const draft = loadDraft(fix.path);
+    const mat = draft.materials.texts.find((t) => t.id === r.json.material_id);
+    assert.equal(mat.text_color, "#00CCFF", "flag overrides preset color");
+    assert.equal(mat.font_size, 24, "unflagged fields still come from the preset");
+    assert.equal(mat.border_width, 20);
+    const seg = draft.tracks.flatMap((t) => t.segments).find((s) => s.id === r.json.segment_id);
+    assert.deepEqual(seg.clip.transform, { x: 0.1, y: 0.3 }, "flagged y wins, preset x kept");
+  });
+
+  it("text-style: explicit flags beat preset values", () => {
+    const added = spawnCli(["add-text", fix.path, "3s", "2s", "restyle me"]);
+    assert.equal(added.status, 0, `stderr: ${added.stderr}`);
+    const r = spawnCli(["text-style", fix.path, added.json.segment_id, "--preset", presetPath, "--border-width", "5"]);
+    assert.equal(r.status, 0, `stderr: ${r.stderr}`);
+    const draft = loadDraft(fix.path);
+    const mat = draft.materials.texts.find((t) => t.id === added.json.material_id);
+    assert.equal(mat.border_width, 5, "flag overrides preset border width");
+    assert.equal(mat.border_color, "#0000FF", "unflagged fields still come from the preset");
+    assert.equal(mat.text_color, "#FF3300");
+  });
+
+  it("text-style accepts --preset with no styling flags", () => {
+    const added = spawnCli(["add-text", fix.path, "6s", "2s", "preset only"]);
+    assert.equal(added.status, 0, `stderr: ${added.stderr}`);
+    const r = spawnCli(["text-style", fix.path, added.json.segment_id, "--preset", presetPath]);
+    assert.equal(r.status, 0, `stderr: ${r.stderr}`);
+    assert.ok(r.json.applied.includes("style"));
+  });
+
+  it("rejects a missing preset file", () => {
+    const r = spawnCli(["add-text", fix.path, "0s", "2s", "x", "--preset", join(out.dir, "nope.json")]);
+    assert.notEqual(r.status, 0);
+    assert.match(r.stderr, /not found/i);
+  });
+
+  it("rejects a preset that is not valid JSON", () => {
+    const bad = join(out.dir, "bad.json");
+    writeFileSync(bad, "{");
+    const r = spawnCli(["add-text", fix.path, "0s", "2s", "x", "--preset", bad]);
+    assert.notEqual(r.status, 0);
+    assert.match(r.stderr, /not valid JSON/i);
+  });
+
+  it("rejects JSON without the capcutCliPreset marker", () => {
+    const bad = join(out.dir, "marker.json");
+    writeFileSync(bad, JSON.stringify({ style: { font_size: 24 } }));
+    const r = spawnCli(["text-style", fix.path, "deadbeef", "--preset", bad]);
+    assert.notEqual(r.status, 0);
+    assert.match(r.stderr, /capcutCliPreset/);
+  });
+
+  it("rejects an unsupported preset version", () => {
+    const bad = join(out.dir, "v2.json");
+    writeFileSync(bad, JSON.stringify({ capcutCliPreset: 2, style: {} }));
+    const r = spawnCli(["add-text", fix.path, "0s", "2s", "x", "--preset", bad]);
+    assert.notEqual(r.status, 0);
+    assert.match(r.stderr, /version/i);
+  });
+
+  it("caption refuses --style-ref together with --preset", () => {
+    const r = spawnCli([
+      "caption",
+      fix.path,
+      "--audio",
+      "missing.wav",
+      "--style-ref",
+      "deadbeef",
+      "--preset",
+      presetPath,
+    ]);
+    assert.notEqual(r.status, 0);
+    assert.match(r.stderr, /mutually exclusive/i);
+  });
+});
+
+describe("capcut make-preset errors", () => {
+  const fix = tmpDraft();
+  const out = tmpDir();
+  after(() => {
+    fix.cleanup();
+    out.cleanup();
+  });
+
+  it("requires --out", () => {
+    const texts = spawnCli(["texts", fix.path]).json ?? [];
+    if (texts.length === 0) return;
+    const r = spawnCli(["make-preset", fix.path, texts[0].id.slice(0, 8)]);
+    assert.notEqual(r.status, 0);
+    assert.match(r.stderr, /--out/);
+  });
+
+  it("rejects a non-text segment", () => {
+    const videoSegs = spawnCli(["segments", fix.path, "--track", "video"]).json ?? [];
+    if (videoSegs.length === 0) return;
+    const r = spawnCli(["make-preset", fix.path, videoSegs[0].id.slice(0, 8), "--out", join(out.dir, "p.json")]);
+    assert.notEqual(r.status, 0);
+    assert.match(r.stderr, /text segments/i);
+  });
+
+  it("rejects an unknown segment", () => {
+    const r = spawnCli(["make-preset", fix.path, "ffffffff", "--out", join(out.dir, "p.json")]);
+    assert.notEqual(r.status, 0);
+    assert.match(r.stderr, /not found/i);
+  });
+});

From 69848f6cb43b7b5eb80ff156a9839280e26d1a48 Mon Sep 17 00:00:00 2001
From: Rene Zander <renezander030@gmail.com>
Date: Wed, 8 Jul 2026 08:06:32 +0000
Subject: [PATCH 07/17] fix(test): use escape sequences instead of raw control
 bytes in sync-timelines fixture

Raw NUL/SOH/STX bytes made git flag the test file as binary, which
would hide its diff from review. Behavior is identical: the JS string
still contains the same three control characters at runtime.
---
 test/sync-timelines.test.mjs | Bin 9259 -> 9277 bytes
 1 file changed, 0 insertions(+), 0 deletions(-)

diff --git a/test/sync-timelines.test.mjs b/test/sync-timelines.test.mjs
index fb879c0d8abba015c13c37753e07b495ae664e2a..b57d3174963ea1fd1d1a6af23b055060ae9a01df 100644
GIT binary patch
delta 59
scmZ4OvDafmmbgevg@FMO8|LMg=w=n?=K<M9n@hz-nX$`Em72y00Bwg9SO5S3

delta 41
lcmdn%vD#xpmN+*9V_trVZdP%A9@FMJaZzRzf#p)uH~|}u4JiNs


From d26453c85134d9c1fdaf2b815d68939fee1e65ea Mon Sep 17 00:00:00 2001
From: Rene Zander <renezander030@gmail.com>
Date: Wed, 8 Jul 2026 08:10:45 +0000
Subject: [PATCH 08/17] chore: release v0.13.0

---
 CHANGELOG.md                 |  17 +-
 README.md                    |  10 +-
 README.zh-CN.md              |  10 +-
 docs/command-reference.json  | 404 ++++++++++++++++++++++++++++++++++-
 docs/command-reference.md    |  10 +-
 docs/version-support.md      |   2 +-
 package-lock.json            |   4 +-
 package.json                 |   2 +-
 test/sync-timelines.test.mjs |   6 +-
 9 files changed, 441 insertions(+), 24 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b526920..b9dfb75 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,11 +2,24 @@
 
 All notable changes to capcut-cli are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.13.0] — 2026-07-08
+
+Six features in one release — the top of the opportunity backlog, bundled. Two build on prior art from the [capcut-cli-david](https://github.com/Davidb-2107/capcut-cli-david) fork (thanks @Davidb-2107); see #36.
 
 ### Added
 
-- `lint <project> --fix` — auto-repair mechanically-fixable draft defects (`cue-too-long`, `caption-overlap`). Trims over-long captions to the configured cap and shortens overlapping caption pairs so each ends where the next begins. Writes atomically with a `.bak` snapshot; combine with `--dry-run` to preview without touching the draft. Non-fixable issues (`missing-material`, `missing-file`, `line-too-long`, `caption-gap-too-small`) are still reported and continue to drive the exit code. Closes #40.
+- `sync-timelines <project> [--apply] [--force-write]` — reconcile a CapCut >= 8.7 draft whose `template-2.tmp` / `draft_info.json` timeline mirror has drifted from `draft_content.json`, so CLI edits are honored by the app instead of silently ignored. `draft_content.json` is always canonical. Plan-only by default (per-target drift report, including `draft_info.json` GUID reconciliation for the pre-open mirror case); `--apply` writes through the existing transactional multi-target save (temp files, `.bak` backups, rollback, optimistic-concurrency check). Refuses to write while the editor is running unless `--force-write`, no-ops with exit 0 when all targets agree, and reports an unreadable (binary/encrypted) `template-2.tmp` as unreconcilable instead of pretending success. `diagnose` now points to `sync-timelines` as the remedy instead of deferring to issue #35. Closes #39.
+- `lint <project> --fix` — auto-repair mechanically-fixable draft defects, now four codes: `cue-too-long` (trims over-long captions to the configured cap), `caption-overlap` (shortens overlapping pairs so each ends where the next begins), `line-too-long` (greedy word wrap that swaps spaces for newlines 1:1, keeping styled-range byte offsets valid; never splits words), and `caption-gap-too-small` (pulls the earlier caption's end back to restore the minimum gap; never moves starts, never creates a new overlap). Writes atomically with a `.bak` snapshot; combine with `--dry-run` to preview. `missing-material` and `missing-file` stay report-only deliberately: the only mechanical repairs would delete user timeline content or act on host-dependent paths. Closes #40.
+- `lint` — new report-only rule `unknown-effect-slug` (warning severity): flags effect/filter/animation resource ids in the draft that are not in the bundled enum table, surfacing them before CapCut silently drops them (the silent-failure mode reported across ecosystem tools, e.g. GuanYixuan/pyCapCut#12).
+- `export-srt <project> [--granularity line|word] [--format srt|vtt]` — word-level caption export. Captions created by `caption --karaoke` carry real per-word timing and export it exactly; plain captions interpolate word timing proportionally by word length (stated in `--help`). SRT + word emits one cue per word; VTT + word emits one cue per phrase with inline `<hh:mm:ss.mmm>` karaoke timestamps for burn-in pipelines. Defaults (`line`, `srt`) reproduce the previous output byte-identically.
+- `keyframe ... --easing <linear|ease-in|ease-out|ease-in-out>` — CapCut-native easing curves, also accepted per-line (`easing` key) in `keyframe --batch` JSONL and in the `compile` spec's keyframe op. The app does not store named curve types: the UI writes `FreeCurveInOut` bezier control handles on both keyframes of the eased segment, and the emitted encodings are locked against a UI-oracle capture (prior art: capcut-cli-david). The `ken-burns` skill default changed linear → ease-out to match what the CapCut UI itself produces.
+- `detect-scenes <video> [--threshold <0..1>] [--min-gap <s>] [--limit <n>] [--json]` — deterministic ffmpeg scene-cut detection (no AI, zero new dependencies) to seed the long-form → shorts flow: prints detected cut points (seconds, `hh:mm:ss.mmm` timecode, scene score) plus a ready-to-use contiguous segment list in seconds and draft-native microseconds. Follows the `probe`/`render` external-binary pattern, including a clear actionable error when ffmpeg is missing.
+- `make-preset <project> <text-segment-id> --out <preset.json>` — extract a hand-tuned text style (font, colors, style flags, alignment/transform, bubble, karaoke/multi-style ranges) from an existing draft into a versioned, portable preset file; apply it with the new `--preset <file>` flag on `add-text`, `text-style`, and `caption`. Explicit CLI flags override preset values. Addresses the recurring ecosystem ask for programmatic font/style reuse (GuanYixuan/pyJianYingDraft#192, Hommy-master/capcut-mate#57).
+
+### Documentation
+
+- `docs/version-support.md` — the CapCut 8.7 row now names `sync-timelines` as the repair path for drifted mirrors.
+- `docs/draft-schema/03-keyframes-and-animations.md` — documents the `FreeCurveInOut` bezier-handle easing encoding.
 
 ## [0.12.0] — 2026-06-27
 
diff --git a/README.md b/README.md
index ebc0fcc..3c2aefd 100644
--- a/README.md
+++ b/README.md
@@ -55,12 +55,12 @@ JSON by default (pipe to `jq`); add `-H` for a human-readable table. Pass `--jia
 | **Create** | `init` · `quickstart` · `compile` (build a draft from a JSON spec) |
 | **Preview** | `render` (low-res ffmpeg proxy — not CapCut's final render) |
 | **Add** | `add-video` · `add-audio` · `add-text` (Wikimedia URLs supported, license-checked) |
-| **Edit / animate** | trim · speed · volume · transitions · masks · text/image animations |
-| **Templates** | apply and extract reusable layouts |
-| **Subtitles & i18n** | `caption` · `import-srt` · `translate` (multi-language draft clone) |
+| **Edit / animate** | trim · speed · volume · transitions · masks · text/image animations · easing curves |
+| **Templates** | apply and extract reusable layouts · `make-preset` (portable text-style presets) |
+| **Subtitles & i18n** | `caption` · `import-srt` · `export-srt` (line/word SRT + VTT) · `translate` (multi-language draft clone) |
 | **Effects** | `sfx` · `chroma` (chroma key) |
-| **Long-form → short** | `cut` |
-| **Automation** | `serve` (stateless JSONL runner) · `migrate` · `doctor` |
+| **Long-form → short** | `cut` · `detect-scenes` (ffmpeg scene-cut detection) |
+| **Automation** | `serve` (stateless JSONL runner) · `migrate` · `doctor` · `sync-timelines` (8.7 mirror repair) |
 
 **Full reference** for every command, option, and exit code: **[docs/command-reference.md](./docs/command-reference.md)**.
 
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 0a3c73b..34fa216 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -55,12 +55,12 @@ capcut info ./my-first/                         # 查看草稿（加 -H 显示
 | **创建** | `init` · `quickstart` · `compile`（用 JSON spec 构建草稿）|
 | **预览** | `render`（低清 ffmpeg 代理预览 —— 非 CapCut 最终渲染）|
 | **添加** | `add-video` · `add-audio` · `add-text`（支持 Wikimedia URL，自动校验授权）|
-| **编辑 / 动画** | 裁剪 · 变速 · 音量 · 转场 · 蒙版 · 文字/图片动画 |
-| **模板** | 应用与提取可复用版式 |
-| **字幕 / 多语言** | `caption` · `import-srt` · `translate`（多语言草稿克隆）|
+| **编辑 / 动画** | 裁剪 · 变速 · 音量 · 转场 · 蒙版 · 文字/图片动画 · 缓动曲线 |
+| **模板** | 应用与提取可复用版式 · `make-preset`（可移植文字样式预设）|
+| **字幕 / 多语言** | `caption` · `import-srt` · `export-srt`（行级/逐词 SRT + VTT）· `translate`（多语言草稿克隆）|
 | **特效** | `sfx` · `chroma`（绿幕抠像）|
-| **长视频切短** | `cut` |
-| **自动化** | `serve`（无状态 JSONL 执行器）· `migrate` · `doctor` |
+| **长视频切短** | `cut` · `detect-scenes`（ffmpeg 场景切点检测）|
+| **自动化** | `serve`（无状态 JSONL 执行器）· `migrate` · `doctor` · `sync-timelines`（8.7 时间线镜像修复）|
 
 **完整命令参考**（每个命令、参数与退出码）：**[docs/command-reference.md](./docs/command-reference.md)**。
 
diff --git a/docs/command-reference.json b/docs/command-reference.json
index ec10d90..d29ddf3 100644
--- a/docs/command-reference.json
+++ b/docs/command-reference.json
@@ -1,6 +1,6 @@
 {
   "name": "capcut-cli",
-  "version": "0.11.3",
+  "version": "0.13.0",
   "schema_version": 2,
   "description": "Edit CapCut/JianYing draft_content.json directly. JSON in, JSON out.",
   "global_flags": [
@@ -513,8 +513,8 @@
     },
     {
       "name": "export-srt",
-      "summary": "Export subtitles to SRT on stdout.",
-      "usage": "capcut export-srt <project>",
+      "summary": "Export subtitles to SRT or WebVTT on stdout, per line or per word.",
+      "usage": "capcut export-srt <project> [options]",
       "positionals": [
         {
           "name": "project",
@@ -522,7 +522,36 @@
           "required": true
         }
       ],
-      "options": [],
+      "options": [
+        {
+          "name": "granularity",
+          "flags": [
+            "--granularity"
+          ],
+          "type": "enum",
+          "required": false,
+          "description": "Cue granularity: one cue per caption or per word.",
+          "values": [
+            "line",
+            "word"
+          ],
+          "default": "line"
+        },
+        {
+          "name": "format",
+          "flags": [
+            "--format"
+          ],
+          "type": "enum",
+          "required": false,
+          "description": "Subtitle output format.",
+          "values": [
+            "srt",
+            "vtt"
+          ],
+          "default": "srt"
+        }
+      ],
       "mutates": false,
       "prerequisites": [],
       "output": {
@@ -898,6 +927,15 @@
           "type": "number",
           "required": false,
           "description": "Vertical position."
+        },
+        {
+          "name": "preset",
+          "flags": [
+            "--preset"
+          ],
+          "type": "path",
+          "required": false,
+          "description": "Apply a make-preset style preset; explicit flags override preset values."
         }
       ],
       "mutates": true,
@@ -957,7 +995,7 @@
     {
       "name": "keyframe",
       "summary": "Add a keyframe (position/scale/rotation/alpha/volume); single or --batch.",
-      "usage": "capcut keyframe <project> <id> <property> <time> <value> | --batch",
+      "usage": "capcut keyframe <project> <id> <property> <time> <value> [--easing <name>] | --batch",
       "positionals": [
         {
           "name": "project",
@@ -983,6 +1021,11 @@
           "name": "value",
           "type": "number",
           "required": true
+        },
+        {
+          "name": "name",
+          "type": "string",
+          "required": false
         }
       ],
       "options": [
@@ -994,6 +1037,22 @@
           "type": "boolean",
           "required": false,
           "description": "Read JSONL keyframes from stdin."
+        },
+        {
+          "name": "easing",
+          "flags": [
+            "--easing"
+          ],
+          "type": "enum",
+          "required": false,
+          "description": "Interpolation easing to adjacent keyframes.",
+          "values": [
+            "linear",
+            "ease-in",
+            "ease-out",
+            "ease-in-out"
+          ],
+          "default": "linear"
         }
       ],
       "mutates": true,
@@ -1469,6 +1528,15 @@
           "type": "number",
           "required": false,
           "description": "Background vertical offset."
+        },
+        {
+          "name": "preset",
+          "flags": [
+            "--preset"
+          ],
+          "type": "path",
+          "required": false,
+          "description": "Apply a make-preset style preset; explicit flags override preset values."
         }
       ],
       "mutates": true,
@@ -2127,6 +2195,44 @@
         "1": "invalid input, warning, or operation failure"
       }
     },
+    {
+      "name": "make-preset",
+      "summary": "Extract a text segment's styling as a reusable preset JSON (apply via --preset).",
+      "usage": "capcut make-preset <project> <text-segment-id> --out <preset.json>",
+      "positionals": [
+        {
+          "name": "project",
+          "type": "path",
+          "required": true
+        },
+        {
+          "name": "text-segment-id",
+          "type": "string",
+          "required": true
+        }
+      ],
+      "options": [
+        {
+          "name": "out",
+          "flags": [
+            "--out"
+          ],
+          "type": "path",
+          "required": false,
+          "description": "Output path."
+        }
+      ],
+      "mutates": false,
+      "prerequisites": [],
+      "output": {
+        "type": "file",
+        "description": "JSON by default; use -H where supported for human output."
+      },
+      "exit_codes": {
+        "0": "success",
+        "1": "invalid input, warning, or operation failure"
+      }
+    },
     {
       "name": "templates",
       "summary": "List bundled reusable templates.",
@@ -2933,6 +3039,15 @@
           "type": "id",
           "required": false,
           "description": "Copy styling from this text segment."
+        },
+        {
+          "name": "preset",
+          "flags": [
+            "--preset"
+          ],
+          "type": "path",
+          "required": false,
+          "description": "Apply a make-preset style preset; explicit flags override preset values."
         }
       ],
       "mutates": true,
@@ -3258,6 +3373,58 @@
         "1": "invalid input, warning, or operation failure"
       }
     },
+    {
+      "name": "replace-media",
+      "summary": "Swap a segment's source file (placeholder > final) keeping its timing, effects, and keyframes.",
+      "usage": "capcut replace-media <project> <segment-id> <new-file> [--retime]",
+      "positionals": [
+        {
+          "name": "project",
+          "type": "path",
+          "required": true
+        },
+        {
+          "name": "segment-id",
+          "type": "id",
+          "required": true
+        },
+        {
+          "name": "new-file",
+          "type": "path",
+          "required": true
+        }
+      ],
+      "options": [
+        {
+          "name": "retime",
+          "flags": [
+            "--retime"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Fit the segment to the new clip instead of preserving in/out."
+        },
+        {
+          "name": "ffprobe_cmd",
+          "flags": [
+            "--ffprobe-cmd"
+          ],
+          "type": "path",
+          "required": false,
+          "description": "ffprobe binary for duration/dimension detection."
+        }
+      ],
+      "mutates": true,
+      "prerequisites": [],
+      "output": {
+        "type": "object",
+        "description": "JSON by default; use -H where supported for human output."
+      },
+      "exit_codes": {
+        "0": "success",
+        "1": "invalid input, warning, or operation failure"
+      }
+    },
     {
       "name": "timeline",
       "summary": "Show the track/segment layout (JSON, or -H ASCII bars).",
@@ -3544,6 +3711,72 @@
         "1": "invalid input, warning, or operation failure"
       }
     },
+    {
+      "name": "fixture",
+      "summary": "Build a shareable, redacted compatibility bundle (timeline JSON only) for a version-support issue.",
+      "usage": "capcut fixture <project> --out <dir>",
+      "positionals": [
+        {
+          "name": "project",
+          "type": "path",
+          "required": true
+        }
+      ],
+      "options": [
+        {
+          "name": "out",
+          "flags": [
+            "--out"
+          ],
+          "type": "path",
+          "required": false,
+          "description": "Output directory for the sanitized bundle."
+        }
+      ],
+      "mutates": false,
+      "prerequisites": [],
+      "output": {
+        "type": "object",
+        "description": "JSON by default; use -H where supported for human output."
+      },
+      "exit_codes": {
+        "0": "success",
+        "1": "invalid input, warning, or operation failure"
+      }
+    },
+    {
+      "name": "sync-timelines",
+      "summary": "Reconcile timeline mirrors (template-2.tmp, draft_info.json) drifted from draft_content.json (plan by default; --apply writes).",
+      "usage": "capcut sync-timelines <project> [--apply]",
+      "positionals": [
+        {
+          "name": "project",
+          "type": "path",
+          "required": true
+        }
+      ],
+      "options": [
+        {
+          "name": "apply",
+          "flags": [
+            "--apply"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Write the reconciled timelines (default: print the plan only)."
+        }
+      ],
+      "mutates": true,
+      "prerequisites": [],
+      "output": {
+        "type": "object",
+        "description": "JSON by default; use -H where supported for human output."
+      },
+      "exit_codes": {
+        "0": "success",
+        "1": "invalid input, warning, or operation failure"
+      }
+    },
     {
       "name": "restore",
       "summary": "Undo writes from .bak / snapshot history (--step N, --list).",
@@ -3795,6 +4028,94 @@
         "1": "invalid input, warning, or operation failure"
       }
     },
+    {
+      "name": "quickstart",
+      "summary": "One-command first draft: create + add one input + lint + print the open-in-CapCut step.",
+      "usage": "capcut quickstart <name> [--video <f>] [--audio <f>] [--srt <f>] [--drafts <dir>]",
+      "positionals": [
+        {
+          "name": "name",
+          "type": "string",
+          "required": true
+        },
+        {
+          "name": "f",
+          "type": "string",
+          "required": false
+        },
+        {
+          "name": "dir",
+          "type": "path",
+          "required": false
+        }
+      ],
+      "options": [
+        {
+          "name": "video",
+          "flags": [
+            "--video"
+          ],
+          "type": "path",
+          "required": false,
+          "description": "Video or image to add."
+        },
+        {
+          "name": "audio",
+          "flags": [
+            "--audio"
+          ],
+          "type": "path",
+          "required": false,
+          "description": "Audio file to add."
+        },
+        {
+          "name": "srt",
+          "flags": [
+            "--srt"
+          ],
+          "type": "path",
+          "required": false,
+          "description": "SRT subtitles to add as caption segments."
+        },
+        {
+          "name": "drafts",
+          "flags": [
+            "--drafts"
+          ],
+          "type": "path",
+          "required": false,
+          "description": "Draft root directory."
+        },
+        {
+          "name": "template",
+          "flags": [
+            "--template"
+          ],
+          "type": "path",
+          "required": false,
+          "description": "Template directory."
+        },
+        {
+          "name": "ffprobe_cmd",
+          "flags": [
+            "--ffprobe-cmd"
+          ],
+          "type": "path",
+          "required": false,
+          "description": "ffprobe binary for duration detection."
+        }
+      ],
+      "mutates": true,
+      "prerequisites": [],
+      "output": {
+        "type": "object",
+        "description": "JSON by default; use -H where supported for human output."
+      },
+      "exit_codes": {
+        "0": "success",
+        "1": "invalid input, warning, or operation failure"
+      }
+    },
     {
       "name": "compile",
       "summary": "Build a draft from a declarative JSON spec (the inverse of describe).",
@@ -3956,6 +4277,79 @@
         "0": "success",
         "1": "invalid input, warning, or operation failure"
       }
+    },
+    {
+      "name": "detect-scenes",
+      "summary": "Detect scene-change cut points in a video (ffmpeg scene filter); prints cuts + segments to seed compile/cut.",
+      "usage": "capcut detect-scenes <video> [options]",
+      "positionals": [
+        {
+          "name": "video",
+          "type": "path",
+          "required": true
+        }
+      ],
+      "options": [
+        {
+          "name": "threshold",
+          "flags": [
+            "--threshold"
+          ],
+          "type": "number",
+          "required": false,
+          "description": "Scene-change score a cut must exceed (0..1).",
+          "default": 0.4
+        },
+        {
+          "name": "min_gap",
+          "flags": [
+            "--min-gap"
+          ],
+          "type": "number",
+          "required": false,
+          "description": "Merge cuts closer than this many seconds, keeping the strongest.",
+          "default": 2
+        },
+        {
+          "name": "limit",
+          "flags": [
+            "--limit"
+          ],
+          "type": "number",
+          "required": false,
+          "description": "Keep only the N strongest cuts."
+        },
+        {
+          "name": "ffmpeg_cmd",
+          "flags": [
+            "--ffmpeg-cmd"
+          ],
+          "type": "path",
+          "required": false,
+          "description": "FFmpeg binary."
+        },
+        {
+          "name": "json",
+          "flags": [
+            "--json"
+          ],
+          "type": "boolean",
+          "required": false,
+          "description": "Force JSON output (the default; overrides -H)."
+        }
+      ],
+      "mutates": false,
+      "prerequisites": [
+        "ffmpeg"
+      ],
+      "output": {
+        "type": "object",
+        "description": "JSON by default; use -H where supported for human output."
+      },
+      "exit_codes": {
+        "0": "success",
+        "1": "invalid input, warning, or operation failure"
+      }
     }
   ]
 }
diff --git a/docs/command-reference.md b/docs/command-reference.md
index 6b8a41a..7484b9d 100644
--- a/docs/command-reference.md
+++ b/docs/command-reference.md
@@ -17,7 +17,7 @@
 | `volume` | `capcut volume <project> <id> <level>` | yes | Set a segment's volume (0.0-1.0). |
 | `trim` | `capcut trim <project> <id> <start> <duration>` | yes | Trim a segment to a start/duration window. |
 | `opacity` | `capcut opacity <project> <id> <alpha>` | yes | Set a segment's opacity (0.0-1.0). |
-| `export-srt` | `capcut export-srt <project>` | no | Export subtitles to SRT on stdout. |
+| `export-srt` | `capcut export-srt <project> [options]` | no | Export subtitles to SRT or WebVTT on stdout, per line or per word. |
 | `materials` | `capcut materials <project> [--type <type>]` | no | List material types and counts; filter with --type. |
 | `segment` | `capcut segment <project> <id>` | no | Full detail for one segment and its material. |
 | `material` | `capcut material <project> <id>` | no | Full detail for one material. |
@@ -25,7 +25,7 @@
 | `add-video` | `capcut add-video <project> <file-or-url> <start> [duration] [options]` | yes | Add a local or Wikimedia video/image on a video track. |
 | `add-text` | `capcut add-text <project> <start> <duration> <text> [options]` | yes | Add a text segment with font/color/position options. |
 | `cut` | `capcut cut <project> <start> <end> --out <path>` | yes | Extract a time range into a new standalone draft. |
-| `keyframe` | `capcut keyframe <project> <id> <property> <time> <value> \| --batch` | yes | Add a keyframe (position/scale/rotation/alpha/volume); single or --batch. |
+| `keyframe` | `capcut keyframe <project> <id> <property> <time> <value> [--easing <name>] \| --batch` | yes | Add a keyframe (position/scale/rotation/alpha/volume); single or --batch. |
 | `transition` | `capcut transition <project> <id> <slug> [--duration <time>]` | yes | Add a transition between segments. |
 | `mask` | `capcut mask <project> <id> <slug> [options] \| --off` | yes | Apply a mask (linear/circle/heart/...) with geometry flags, or --off. |
 | `bg-blur` | `capcut bg-blur <project> <id> <level> \| --off` | yes | Set background blur level 1-4, or --off. |
@@ -41,6 +41,7 @@
 | `add-effect` | `capcut add-effect <project> <slug> <start> <duration> [options]` | yes | Add a scene effect on its own track. |
 | `save-template` | `capcut save-template <project> <id> <name> --out <path>` | no | Extract a segment as a reusable template JSON. |
 | `apply-template` | `capcut apply-template <project> <template> <start> <duration> [text] [options]` | yes | Stamp a template into a project with new timing/text. |
+| `make-preset` | `capcut make-preset <project> <text-segment-id> --out <preset.json>` | no | Extract a text segment's styling as a reusable preset JSON (apply via --preset). |
 | `templates` | `capcut templates <project>` | no | List bundled reusable templates. |
 | `batch` | `capcut batch <project> [--continue-on-error] < operations.jsonl` | yes | Run multiple edits from stdin (JSONL), one file write. |
 | `import-srt` | `capcut import-srt <project> <srt-or-> [options]` | yes | Import an SRT file/stdin as one text segment per cue. |
@@ -53,6 +54,7 @@
 | `chroma` | `capcut chroma <project> <id> (--color <hex> \| --off) [options]` | yes | Green-screen / chroma key a video segment, or --off. |
 | `prune` | `capcut prune <project>` | yes | Remove materials no segment references. |
 | `relink` | `capcut relink <project> (--dir <path> \| --from <prefix> --to <prefix>)` | yes | Repair broken media paths (--dir or --from/--to). |
+| `replace-media` | `capcut replace-media <project> <segment-id> <new-file> [--retime]` | yes | Swap a segment's source file (placeholder > final) keeping its timing, effects, and keyframes. |
 | `timeline` | `capcut timeline <project> [--cols <number>]` | no | Show the track/segment layout (JSON, or -H ASCII bars). |
 | `projects` | `capcut projects [query] [--drafts <path>] [--names]` | no | List CapCut/JianYing draft folders on disk. |
 | `diff` | `capcut diff <project-a> <project-b>` | no | Compare two drafts (segments/materials/tracks added/removed/changed). |
@@ -63,10 +65,14 @@
 | `enums` | `capcut enums <category-flag> [--jianying]` | no | List enum slugs (transitions, masks, effects, ...) by category. |
 | `doctor` | `capcut doctor` | no | Environment preflight (Node, whisper, API key, project dir). |
 | `diagnose` | `capcut diagnose <project> [--bundle <report.json>]` | no | Inspect canonical draft files, divergence, and editor-write safety. |
+| `fixture` | `capcut fixture <project> --out <dir>` | no | Build a shareable, redacted compatibility bundle (timeline JSON only) for a version-support issue. |
+| `sync-timelines` | `capcut sync-timelines <project> [--apply]` | yes | Reconcile timeline mirrors (template-2.tmp, draft_info.json) drifted from draft_content.json (plan by default; --apply writes). |
 | `restore` | `capcut restore <project> [--step <number> \| --list]` | yes | Undo writes from .bak / snapshot history (--step N, --list). |
 | `serve` | `capcut serve [--queue <path>] [options]` | no | Run a stateless JSONL job queue from stdin/--queue. |
 | `decrypt` | `capcut decrypt <project-or-file>` | no | Detect JianYing 6.0+ encryption and explain the workaround. |
 | `export` | `capcut export <drafts-dir> --batch [options]` | yes | EXPERIMENTAL UI-automated render queue (macOS). |
 | `init` | `capcut init <name> [--template <dir>] [--drafts <dir>]` | yes | Create a new empty draft from a template. |
+| `quickstart` | `capcut quickstart <name> [--video <f>] [--audio <f>] [--srt <f>] [--drafts <dir>]` | yes | One-command first draft: create + add one input + lint + print the open-in-CapCut step. |
 | `compile` | `capcut compile <spec.json> [--out <draftdir>] [--check \| --plan]` | yes | Build a draft from a declarative JSON spec (the inverse of describe). |
 | `render` | `capcut render <project> [--out <preview.mp4>] [options]` | no | Render a low-res ffmpeg proxy preview (trim+speed+audio, --burn-captions); not CapCut's final render. |
+| `detect-scenes` | `capcut detect-scenes <video> [options]` | no | Detect scene-change cut points in a video (ffmpeg scene filter); prints cuts + segments to seed compile/cut. |
diff --git a/docs/version-support.md b/docs/version-support.md
index 1e9e6da..c190dea 100644
--- a/docs/version-support.md
+++ b/docs/version-support.md
@@ -18,7 +18,7 @@ Run `capcut version <project>` for schema flags and `capcut diagnose <project> -
 |---|---|---|---|
 | 6.2.8 | fixture-tested | supported | Canonical fixture in `test/draft_content.json`; full command suite. |
 | 6.5–8.0 | expected-compatible | unverified | No committed app-created fixtures. Enum/schema changes appear additive. |
-| 8.7 Windows | reported + synthetic-tested | adapter shipped, real validation pending | Issue #35 reports that `draft_content.json` edits may be ignored in favour of `template-2.tmp` / `draft_meta_info.json`. v0.11 discovers nested/string JSON timeline envelopes, selects modern storage, synchronizes every readable target, and provides `diagnose --bundle` and `fixture --out` (one-command sanitized bundle). A reporter-provided real folder is still required before marking this fixture-tested. |
+| 8.7 Windows | reported + synthetic-tested | adapter shipped, real validation pending | Issue #35 reports that `draft_content.json` edits may be ignored in favour of `template-2.tmp` / `draft_meta_info.json`. v0.11 discovers nested/string JSON timeline envelopes, selects modern storage, synchronizes every readable target, and provides `diagnose --bundle` and `fixture --out` (one-command sanitized bundle). v0.13 adds `sync-timelines` to reconcile an already-drifted mirror (plan by default, `--apply` to write); `diagnose` names it as the remedy. A reporter-provided real folder is still required before marking this fixture-tested. |
 | 9.x | expected-compatible | unverified | `common_masks` may coexist with legacy mask fields. Use `version`, `diagnose`, and `migrate`; do not treat this row as desktop-app verification. |
 
 There is no blanket “6.x–9.x tested” claim. Only versions with committed fixtures receive that label.
diff --git a/package-lock.json b/package-lock.json
index e5e5933..0c1ed5f 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "capcut-cli",
-  "version": "0.11.3",
+  "version": "0.13.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "capcut-cli",
-      "version": "0.11.3",
+      "version": "0.13.0",
       "license": "MIT",
       "bin": {
         "capcut": "dist/index.js",
diff --git a/package.json b/package.json
index dc89798..990cb86 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "capcut-cli",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Independent, unofficial CLI to create and edit CapCut projects — build drafts from scratch, add video/audio/text, subtitles, timing, speed, volume, templates, cut long-form to shorts. No API needed. Not affiliated with ByteDance.",
   "type": "module",
   "bin": {
diff --git a/test/sync-timelines.test.mjs b/test/sync-timelines.test.mjs
index b57d317..10faddf 100644
--- a/test/sync-timelines.test.mjs
+++ b/test/sync-timelines.test.mjs
@@ -140,7 +140,11 @@ describe("sync-timelines", () => {
     assert.deepEqual(r.json.reconciled, ["draft_info.json"], "only the readable mirror is repaired");
     assert.equal(r.json.unreconcilable[0].file, "template-2.tmp");
     assert.match(r.stderr, /WARNING template-2\.tmp/);
-    assert.equal(readFileSync(join(f.dir, "template-2.tmp"), "utf-8"), "\x00\x01not-json\x02", "binary mirror left untouched");
+    assert.equal(
+      readFileSync(join(f.dir, "template-2.tmp"), "utf-8"),
+      "\x00\x01not-json\x02",
+      "binary mirror left untouched",
+    );
 
     // The remaining unreconcilable mirror keeps ok=false honesty on later runs.
     const again = spawnCli(["sync-timelines", f.dir]);

From f17239941fc03bec386ddbdb98a2b8bf833be623 Mon Sep 17 00:00:00 2001
From: Rene Zander <renezander030@gmail.com>
Date: Wed, 8 Jul 2026 10:24:41 +0000
Subject: [PATCH 09/17] fix(lint): honor render floor in gap repair, correct
 wrap break position, per-instance fixable stamps, unknown-effect-slug to info

Fixes four confirmed v0.13.0 code-review findings:

- caption-gap-too-small --fix crushed captions to sub-frame slivers
  (e.g. 50,003us -> 1us) and reported FIXED. Pass 3 now never shrinks a
  caption below MIN_CAPTION_DURATION_US (100ms = three frames at the
  30fps draft default); unclearable gap issues are skipped and stamped
  fixable:false.

- wrapLine kept a multi-space run's surplus spaces on the broken line,
  so the fixed line could still exceed --max-chars: --fix then either
  never converged (identical issue survived every run, draft never
  saved) or degraded trailing-space lines into stacked blank caption
  lines. The break now replaces a space chosen so no emitted line
  exceeds the cap; re-running the wrap is a no-op, so --fix converges.

- line-too-long was stamped fixable:true on instances pass 4 provably
  cannot fix (raw-JSON fallback content without a text field, space-less
  CJK text, single words over the cap). The stamp is now computed per
  instance: only when the fixer reads the same string as the checker and
  re-wrapping clears every over-cap line.

- unknown-effect-slug false-positived on UI-authored drafts using
  store-downloaded effects (unbounded catalogue the bundled enum table
  cannot cover) and flipped lint exit codes 0 -> 1 in CI. Downgraded to
  info severity: still reported for CLI-authored drafts, but never
  affects the exit code.

Updates lint --help (fixable codes, 100ms floor, info-level exit-code
note) and adds regression tests mirroring the review reproductions.
---
 src/index.ts       |  14 ++-
 src/lint.ts        |  94 +++++++++++-----
 test/lint.test.mjs | 260 ++++++++++++++++++++++++++++++++++++++++++++-
 3 files changed, 336 insertions(+), 32 deletions(-)

diff --git a/src/index.ts b/src/index.ts
index 4ca520f..dd6a276 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -200,10 +200,16 @@ Overview (start here):
                --max-cue-secs <n>  Caption duration cap (default 7)
                --min-gap-ms <n>    Min gap between captions (default 0)
                --no-check-paths    Skip local-file existence checks
-               --fix               Auto-repair mechanically-fixable issues
-                                   (cue-too-long, caption-overlap). Combine
-                                   with --dry-run to preview without writing.
-             Exit codes: 0 clean · 1 warnings · 2 errors
+               --fix               Auto-repair issues stamped fixable:true
+                                   (cue-too-long, caption-overlap,
+                                   caption-gap-too-small, line-too-long).
+                                   Never shrinks a caption below 100ms and
+                                   never splits words; instances it cannot
+                                   repair are reported with fixable:false.
+                                   Combine with --dry-run to preview.
+             Exit codes: 0 clean · 1 warnings · 2 errors. Info-level issues
+             (e.g. unknown-effect-slug, which store-downloaded effects from
+             the CapCut app trigger legitimately) never affect the exit code.
 
 Browse:
   segments   <project> [--track <type>]         List segments with timing
diff --git a/src/lint.ts b/src/lint.ts
index ada1563..f599d8a 100644
--- a/src/lint.ts
+++ b/src/lint.ts
@@ -20,8 +20,10 @@ export interface LintIssue {
   };
 }
 
-// Codes that lintDraft can mechanically repair via fixDraft. Any issue whose
-// code appears here is emitted with fixable:true.
+// Codes that lintDraft can mechanically repair via fixDraft. Membership here
+// is necessary but not sufficient for fixable:true — line-too-long and
+// caption-gap-too-small are additionally stamped per instance, so an issue is
+// only marked fixable when fixDraft can actually clear that exact instance.
 //
 // Deliberately NOT here: missing-material and missing-file (the only safe
 // repair would delete user timeline content or guess a path — report-only;
@@ -29,6 +31,14 @@ export interface LintIssue {
 // (repair would mean guessing which resource the author meant).
 const FIXABLE_CODES = new Set<string>(["cue-too-long", "caption-overlap", "caption-gap-too-small", "line-too-long"]);
 
+// Floor for any duration --fix writes: 100ms = three frames at the 30fps
+// draft default. Below roughly one frame (33,333us at 30fps) CapCut cannot
+// render the caption at all, so a "repair" that short would silently delete
+// it from playback. Pass 3 skips shrinks that would land under this floor and
+// the corresponding caption-gap-too-small issue is reported with
+// fixable:false instead.
+export const MIN_CAPTION_DURATION_US = 100_000;
+
 export interface LintOptions {
   maxCharsPerLine: number;
   maxCueDurationUs: number;
@@ -83,7 +93,10 @@ export function lintDraft(draft: Draft, opts: LintOptions = DEFAULT_LINT_OPTIONS
             severity: "warning",
             code: "line-too-long",
             message: `Caption ${shortId(s.id)} has ${line.length}-char line (>${opts.maxCharsPerLine}): "${line.slice(0, 50)}…"`,
-            fixable: FIXABLE_CODES.has("line-too-long"),
+            fixable:
+              FIXABLE_CODES.has("line-too-long") &&
+              mat !== undefined &&
+              canFixLineTooLong(mat.content, opts.maxCharsPerLine),
             location: { track: track.name, segment_id: s.id },
           });
           break;
@@ -103,11 +116,15 @@ export function lintDraft(draft: Draft, opts: LintOptions = DEFAULT_LINT_OPTIONS
             location: { track: track.name, segment_id: s.id },
           });
         } else if (gap > 0 && gap < opts.minGapBetweenCaptionsUs) {
+          // Fixable only when pass 3's shrink leaves the earlier caption at or
+          // above MIN_CAPTION_DURATION_US — otherwise the repair would crush
+          // it to an unrenderable sliver, so it is report-only.
+          const shrunkDuration = s.target_timerange.duration - (opts.minGapBetweenCaptionsUs - gap);
           issues.push({
             severity: "warning",
             code: "caption-gap-too-small",
             message: `Captions ${shortId(s.id)} and ${shortId(next.id)} are ${Math.round(gap / 1000)}ms apart (<${opts.minGapBetweenCaptionsUs / 1000}ms)`,
-            fixable: FIXABLE_CODES.has("caption-gap-too-small"),
+            fixable: FIXABLE_CODES.has("caption-gap-too-small") && shrunkDuration >= MIN_CAPTION_DURATION_US,
             location: { track: track.name, segment_id: s.id },
           });
         }
@@ -136,14 +153,18 @@ export function lintDraft(draft: Draft, opts: LintOptions = DEFAULT_LINT_OPTIONS
 
   // Effect/filter/animation resource ids the bundled enum table doesn't know.
   // CapCut silently drops unknown resource ids (GuanYixuan/pyCapCut#12), so
-  // surface them before the app eats them. Report-only: a repair would mean
-  // guessing which resource the author meant.
+  // surface them before the app eats them. Severity is info, not warning: the
+  // bundled table only covers ids the CLI itself can write, while drafts made
+  // in the CapCut app routinely use store-downloaded effects no table could
+  // ever cover — a warning here would flip exit codes (0 -> 1) on perfectly
+  // valid UI-authored drafts. Report-only: a repair would mean guessing which
+  // resource the author meant.
   const known = knownEffectIds();
   const pushUnknown = (kind: string, name: string, badId: string, materialId: string) => {
     issues.push({
-      severity: "warning",
+      severity: "info",
       code: "unknown-effect-slug",
-      message: `${kind} "${name}" (material ${shortId(materialId)}) uses effect_id ${badId} not in the bundled enum table — CapCut may silently ignore it`,
+      message: `${kind} "${name}" (material ${shortId(materialId)}) uses effect_id ${badId} not in the bundled enum table — fine for store effects added in the CapCut app, but ids the CLI wrote from a stale slug may be silently ignored`,
       fixable: FIXABLE_CODES.has("unknown-effect-slug"),
       location: { material_id: materialId },
     });
@@ -280,7 +301,9 @@ export function fixDraft(draft: Draft, opts: LintOptions = DEFAULT_LINT_OPTIONS)
 
   // Pass 3: widen under-min gaps by pulling the earlier caption's end back —
   // the same mutation direction as pass 2, so it can never create a new
-  // overlap or move a start. Skipped when the shrink would erase the caption.
+  // overlap or move a start. Skipped when the shrink would leave the caption
+  // under MIN_CAPTION_DURATION_US: a sub-frame sliver is as gone as a deleted
+  // caption, so those issues stay reported (with fixable:false) instead.
   if (opts.minGapBetweenCaptionsUs > 0) {
     for (const track of getTracksByType(draft, "text")) {
       const segs = [...track.segments].sort((a, b) => a.target_timerange.start - b.target_timerange.start);
@@ -291,7 +314,7 @@ export function fixDraft(draft: Draft, opts: LintOptions = DEFAULT_LINT_OPTIONS)
         const gap = next.target_timerange.start - end;
         if (gap > 0 && gap < opts.minGapBetweenCaptionsUs) {
           const newDuration = s.target_timerange.duration - (opts.minGapBetweenCaptionsUs - gap);
-          if (newDuration <= 0) continue;
+          if (newDuration < MIN_CAPTION_DURATION_US) continue;
           const oldDuration = s.target_timerange.duration;
           s.target_timerange.duration = newDuration;
           if (s.source_timerange && s.source_timerange.duration === oldDuration) {
@@ -334,6 +357,26 @@ export function fixDraft(draft: Draft, opts: LintOptions = DEFAULT_LINT_OPTIONS)
   return { fixed, remaining };
 }
 
+// True when pass 4's re-wrap would actually clear a line-too-long issue on
+// this material — the per-instance half of the fixable stamp. Three ways it
+// cannot: content isn't JSON, or has no non-empty string `text` (the checker's
+// extractText then measures a fallback string the fixer never touches), or
+// re-wrapping still leaves an over-cap line (space-less text such as CJK
+// captions, or single words longer than the cap — wrapping only swaps spaces
+// for newlines, so those stay reported).
+function canFixLineTooLong(content: string, maxChars: number): boolean {
+  let parsed: { text?: unknown };
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    return false;
+  }
+  if (typeof parsed.text !== "string" || parsed.text === "") return false;
+  return rewrapText(parsed.text, maxChars)
+    .split(/\r?\n/)
+    .every((line) => line.length <= maxChars);
+}
+
 // Re-wrap only lines that exceed maxChars; existing line breaks are kept.
 function rewrapText(text: string, maxChars: number): string {
   return text
@@ -343,23 +386,26 @@ function rewrapText(text: string, maxChars: number): string {
 }
 
 // Greedy word wrap that only swaps spaces for newlines (1:1, length-neutral).
-// A multi-space separator keeps its extra spaces at the end of the broken line.
+// Each break replaces one space with '\n', picked so the emitted line never
+// exceeds maxChars — inside a multi-space run the surplus spaces land after
+// the break instead of overflowing the broken line. A segment with no space
+// at or before the cap (an over-long word, space-less CJK text) is emitted
+// unchanged, so re-running the wrap is always a no-op and --fix converges.
 function wrapLine(line: string, maxChars: number): string {
-  const tokens = line.split(/( +)/); // words at even indices, space runs at odd
-  let out = tokens[0] ?? "";
-  let lineLen = out.length;
-  for (let i = 1; i < tokens.length; i += 2) {
-    const sep = tokens[i];
-    const word = tokens[i + 1] ?? "";
-    if (lineLen > 0 && lineLen + sep.length + word.length > maxChars) {
-      out += `${sep.slice(0, -1)}\n${word}`;
-      lineLen = word.length;
-    } else {
-      out += sep + word;
-      lineLen += sep.length + word.length;
+  let out = "";
+  let rest = line;
+  while (rest.length > maxChars) {
+    // Break at the last space that keeps the emitted line within maxChars…
+    let brk = rest.lastIndexOf(" ", maxChars);
+    if (brk === -1) {
+      // …or after an unbreakable over-long head, at the first space past it.
+      brk = rest.indexOf(" ", maxChars);
+      if (brk === -1) break;
     }
+    out += `${rest.slice(0, brk)}\n`;
+    rest = rest.slice(brk + 1);
   }
-  return out;
+  return out + rest;
 }
 
 function issueKey(i: LintIssue): string {
diff --git a/test/lint.test.mjs b/test/lint.test.mjs
index 7207e26..93169a4 100644
--- a/test/lint.test.mjs
+++ b/test/lint.test.mjs
@@ -4,6 +4,41 @@ import { after, describe, it } from "node:test";
 import { spawnCli } from "./helpers/spawn-cli.mjs";
 import { tmpDraft } from "./helpers/tmp-draft.mjs";
 
+// Seed a dedicated text track (own materials, own segments) into a fixture
+// draft, so timing rules can't interact with the fixture's Subtitles track.
+function seedTextTrack(draftPath, trackId, materials, segments) {
+  const draft = JSON.parse(readFileSync(draftPath, "utf-8"));
+  draft.materials.texts = [...(draft.materials.texts ?? []), ...materials];
+  draft.tracks.push({ id: trackId, type: "text", name: trackId, attribute: 0, segments });
+  writeFileSync(draftPath, JSON.stringify(draft));
+}
+
+function textMat(id, text) {
+  return {
+    id,
+    type: "text",
+    content: JSON.stringify({ text, styles: [] }),
+    font_size: 15,
+    text_color: "#FFFFFF",
+    alignment: 1,
+  };
+}
+
+function textSeg(id, materialId, startUs, durationUs) {
+  return {
+    id,
+    material_id: materialId,
+    target_timerange: { start: startUs, duration: durationUs },
+    source_timerange: { start: 0, duration: durationUs },
+    speed: 1,
+    volume: 1,
+    visible: true,
+    clip: { alpha: 1, rotation: 0, scale: { x: 1, y: 1 }, transform: { x: 0, y: 0 } },
+    extra_material_refs: [],
+    render_index: 0,
+  };
+}
+
 describe("capcut lint", () => {
   describe("on a clean fixture", () => {
     const fix = tmpDraft();
@@ -407,7 +442,7 @@ describe("capcut lint", () => {
       const fix = tmpDraft();
       after(() => fix.cleanup());
 
-      it("warns on bogus effect and animation ids as report-only", () => {
+      it("reports bogus effect and animation ids as info, without failing the exit code", () => {
         const draft = JSON.parse(readFileSync(fix.path, "utf-8"));
         draft.materials.video_effects = [
           baseEffectMaterial("bogus-effect-mat", "Stale Effect", "1111111111111111111", "1111111111111111111"),
@@ -438,12 +473,16 @@ describe("capcut lint", () => {
         const materialIds = unknown.map((i) => i.location.material_id).sort();
         assert.deepEqual(materialIds, ["bogus-anim-container", "bogus-effect-mat"]);
         for (const i of unknown) {
-          assert.equal(i.severity, "warning");
+          assert.equal(i.severity, "info");
           assert.equal(i.fixable, false);
         }
-        // Warnings-only draft → exit 1 per the CI contract.
+        // Info only — the bundled table can't know store-downloaded effects,
+        // so a UI-authored draft must keep exiting 0 (regression: v0.13 review
+        // found this check flipping CI gates to exit 1 on valid drafts).
         assert.equal(r.json.summary.errors, 0);
-        assert.equal(r.status, 1);
+        assert.equal(r.json.summary.warnings, 0);
+        assert.equal(r.json.summary.info, 2);
+        assert.equal(r.status, 0);
 
         // Report-only: --fix must not claim it repaired anything here.
         const fixRun = spawnCli(["lint", fix.path, "--fix", "--no-check-paths"]);
@@ -477,4 +516,217 @@ describe("capcut lint", () => {
       });
     });
   });
+
+  describe("--fix gap repair never crushes a caption below the render floor", () => {
+    const fix = tmpDraft();
+    after(() => fix.cleanup());
+
+    it("skips the shrink and stamps the issue fixable:false when it would leave a sub-frame sliver", () => {
+      // Mirror of the v0.13 review reproduction: caption A runs 50,003us and B
+      // starts 49,998us after A ends. Closing the gap to 100ms would leave A
+      // at 1us — far below one 30fps frame (33,333us), i.e. deleted from
+      // playback — yet the old fixer did exactly that and reported FIXED.
+      seedTextTrack(
+        fix.path,
+        "gap-floor-track",
+        [textMat("gap-floor-mat", "Hi")],
+        [
+          textSeg("gapfloor-1-aaaa-bbbb-cccc-dddddddddddd", "gap-floor-mat", 500_000_000, 50_003),
+          textSeg("gapfloor-2-aaaa-bbbb-cccc-dddddddddddd", "gap-floor-mat", 500_100_001, 1_000_000),
+        ],
+      );
+
+      const detect = spawnCli(["lint", fix.path, "--min-gap-ms", "100", "--no-check-paths"]);
+      const found = detect.json.issues.filter((i) => i.code === "caption-gap-too-small");
+      assert.equal(found.length, 1, `expected one caption-gap-too-small; got: ${JSON.stringify(detect.json.issues)}`);
+      assert.equal(found[0].fixable, false, "a gap --fix cannot clear must not be stamped fixable:true");
+
+      const before = readFileSync(fix.path, "utf-8");
+      const r = spawnCli(["lint", fix.path, "--fix", "--min-gap-ms", "100", "--no-check-paths"]);
+      assert.ok(
+        !r.json.fixed.some((i) => i.code === "caption-gap-too-small"),
+        `must not claim FIXED; got: ${JSON.stringify(r.json.fixed)}`,
+      );
+      assert.ok(r.json.issues.some((i) => i.code === "caption-gap-too-small" && i.fixable === false));
+      assert.equal(r.status, 1, "the surviving warning keeps exit code 1");
+
+      // Nothing was repairable, so the draft must not be rewritten at all.
+      assert.equal(readFileSync(fix.path, "utf-8"), before, "--fix must not save a draft it didn't repair");
+      const repaired = JSON.parse(before);
+      const segA = repaired.tracks
+        .find((t) => t.id === "gap-floor-track")
+        .segments.find((s) => s.id.startsWith("gapfloor-1"));
+      assert.equal(segA.target_timerange.duration, 50_003, "caption A must keep its full duration");
+    });
+  });
+
+  describe("--fix gap repair still applies when the result stays at or above the floor", () => {
+    const fix = tmpDraft();
+    after(() => fix.cleanup());
+
+    it("shrinks a caption down to exactly the 100ms floor and re-lints clean", () => {
+      // gap = 49,998us (<100ms); the needed 50,002us shrink lands A exactly on
+      // the 100,000us floor — the tightest still-allowed repair.
+      seedTextTrack(
+        fix.path,
+        "gap-edge-track",
+        [textMat("gap-edge-mat", "Hi")],
+        [
+          textSeg("gapedge-1-aaaa-bbbb-cccc-dddddddddddd", "gap-edge-mat", 600_000_000, 150_002),
+          textSeg("gapedge-2-aaaa-bbbb-cccc-dddddddddddd", "gap-edge-mat", 600_200_000, 1_000_000),
+        ],
+      );
+
+      const detect = spawnCli(["lint", fix.path, "--min-gap-ms", "100", "--no-check-paths"]);
+      const found = detect.json.issues.filter((i) => i.code === "caption-gap-too-small");
+      assert.equal(found.length, 1);
+      assert.equal(found[0].fixable, true);
+
+      const r = spawnCli(["lint", fix.path, "--fix", "--min-gap-ms", "100", "--no-check-paths"]);
+      assert.ok(
+        r.json.fixed.some((i) => i.code === "caption-gap-too-small"),
+        `expected the gap in fixed[]; got: ${JSON.stringify(r.json.fixed)}`,
+      );
+      assert.equal(r.status, 0);
+
+      const repaired = JSON.parse(readFileSync(fix.path, "utf-8"));
+      const segA = repaired.tracks
+        .find((t) => t.id === "gap-edge-track")
+        .segments.find((s) => s.id.startsWith("gapedge-1"));
+      assert.equal(segA.target_timerange.duration, 100_000, "caption A shrinks exactly to the floor");
+    });
+  });
+
+  describe("--fix wraps lines whose break lands in a multi-space run", () => {
+    const fix = tmpDraft();
+    after(() => fix.cleanup());
+
+    it("never leaves an output line over --max-chars and stays length-neutral", () => {
+      // Mirror of the v0.13 review reproduction: with the break placed at the
+      // END of the space run, 'abcdefgh      xy' "wrapped" to a 13-char first
+      // line that still violated the 10-char cap forever.
+      const text = "abcdefgh      xy"; // 8 chars + 6 spaces + 2 chars
+      seedTextTrack(
+        fix.path,
+        "wrap-run-track",
+        [textMat("wrap-run-mat", text)],
+        [textSeg("wraprun-1-aaaa-bbbb-cccc-dddddddddddd", "wrap-run-mat", 700_000_000, 1_000_000)],
+      );
+
+      const detect = spawnCli(["lint", fix.path, "--max-chars", "10", "--no-check-paths"]);
+      const mine = detect.json.issues.filter(
+        (i) => i.code === "line-too-long" && i.location?.segment_id?.startsWith("wraprun-1"),
+      );
+      assert.equal(mine.length, 1, `expected line-too-long; got: ${JSON.stringify(detect.json.issues)}`);
+      assert.equal(mine[0].fixable, true);
+
+      const r = spawnCli(["lint", fix.path, "--fix", "--max-chars", "10", "--no-check-paths"]);
+      assert.ok(
+        r.json.fixed.some((i) => i.code === "line-too-long" && i.location?.segment_id?.startsWith("wraprun-1")),
+        `expected the wrap in fixed[]; got: ${JSON.stringify(r.json.fixed)}`,
+      );
+      assert.ok(
+        !r.json.issues.some((i) => i.code === "line-too-long" && i.location?.segment_id?.startsWith("wraprun-1")),
+        `line-too-long must not survive --fix here; got: ${JSON.stringify(r.json.issues)}`,
+      );
+
+      const repaired = JSON.parse(readFileSync(fix.path, "utf-8"));
+      const content = JSON.parse(repaired.materials.texts.find((m) => m.id === "wrap-run-mat").content);
+      assert.equal(content.text.length, text.length, "wrap must stay length-neutral");
+      assert.equal(content.text.replace(/\n/g, " "), text, "only spaces may become newlines");
+      for (const line of content.text.split("\n")) {
+        assert.ok(line.length <= 10, `broken line still exceeds the cap: ${JSON.stringify(line)}`);
+      }
+    });
+  });
+
+  describe("--fix converges on lines ending in a space run", () => {
+    const fix = tmpDraft();
+    after(() => fix.cleanup());
+
+    it("wraps once and a second --fix is a byte-identical no-op (no stacked blank lines)", () => {
+      // Mirror of the v0.13 review reproduction: 'aaaaaaaaaa   ' degraded one
+      // trailing space per --fix run into stacked blank caption lines.
+      const text = "aaaaaaaaaa   "; // 10 chars + 3 trailing spaces
+      seedTextTrack(
+        fix.path,
+        "wrap-tail-track",
+        [textMat("wrap-tail-mat", text)],
+        [textSeg("wraptail-1-aaaa-bbbb-cccc-dddddddddddd", "wrap-tail-mat", 750_000_000, 1_000_000)],
+      );
+
+      const r1 = spawnCli(["lint", fix.path, "--fix", "--max-chars", "10", "--no-check-paths"]);
+      assert.ok(
+        !r1.json.issues.some((i) => i.code === "line-too-long" && i.location?.segment_id?.startsWith("wraptail-1")),
+        `the trailing-run line must be clean after one --fix; got: ${JSON.stringify(r1.json.issues)}`,
+      );
+      const afterFirst = readFileSync(fix.path, "utf-8");
+      const content = JSON.parse(JSON.parse(afterFirst).materials.texts.find((m) => m.id === "wrap-tail-mat").content);
+      assert.equal(content.text, "aaaaaaaaaa\n  ", "the surplus spaces move past the break, not onto the full line");
+
+      const r2 = spawnCli(["lint", fix.path, "--fix", "--max-chars", "10", "--no-check-paths"]);
+      assert.equal(r2.json.fixed.length, 0, `second --fix must fix nothing; got: ${JSON.stringify(r2.json.fixed)}`);
+      assert.equal(readFileSync(fix.path, "utf-8"), afterFirst, "--fix must converge, not keep mutating the draft");
+    });
+  });
+
+  describe("line-too-long fixable stamping matches what --fix can actually do", () => {
+    const fix = tmpDraft();
+    after(() => fix.cleanup());
+
+    it("stamps fixable:false on raw-JSON fallback, space-less CJK, and over-cap single words", () => {
+      // Three shapes the re-wrapper provably cannot clear (v0.13 review):
+      // 1) content JSON without a text field — the checker measures the raw
+      //    content fallback, which the fixer never touches;
+      // 2) space-less CJK text — no space to swap for a newline;
+      // 3) a single word longer than the cap — words are never split.
+      const noTextContent = JSON.stringify({ styles: [{ range: [0, 10] }], noText: "x".repeat(160) });
+      seedTextTrack(
+        fix.path,
+        "stamp-track",
+        [
+          {
+            id: "stamp-notext-mat",
+            type: "text",
+            content: noTextContent,
+            font_size: 15,
+            text_color: "#FFFFFF",
+            alignment: 1,
+          },
+          textMat("stamp-cjk-mat", "字".repeat(60)),
+          textMat("stamp-word-mat", "x".repeat(60)),
+        ],
+        [
+          textSeg("stamp-1-aaaa-bbbb-cccc-dddddddddddd", "stamp-notext-mat", 800_000_000, 1_000_000),
+          textSeg("stamp-2-aaaa-bbbb-cccc-dddddddddddd", "stamp-cjk-mat", 802_000_000, 1_000_000),
+          textSeg("stamp-3-aaaa-bbbb-cccc-dddddddddddd", "stamp-word-mat", 804_000_000, 1_000_000),
+        ],
+      );
+
+      const detect = spawnCli(["lint", fix.path, "--no-check-paths"]);
+      const mine = detect.json.issues.filter(
+        (i) => i.code === "line-too-long" && i.location?.segment_id?.startsWith("stamp-"),
+      );
+      assert.equal(mine.length, 3, `expected three line-too-long issues; got: ${JSON.stringify(detect.json.issues)}`);
+      for (const i of mine) {
+        assert.equal(
+          i.fixable,
+          false,
+          `--fix cannot clear this instance, so it must not be stamped: ${JSON.stringify(i)}`,
+        );
+      }
+
+      const before = readFileSync(fix.path, "utf-8");
+      const r = spawnCli(["lint", fix.path, "--fix", "--no-check-paths"]);
+      assert.ok(
+        !r.json.fixed.some((i) => i.code === "line-too-long"),
+        `nothing here is repairable; got: ${JSON.stringify(r.json.fixed)}`,
+      );
+      const remaining = r.json.issues.filter(
+        (i) => i.code === "line-too-long" && i.location?.segment_id?.startsWith("stamp-"),
+      );
+      assert.equal(remaining.length, 3, "all three stay reported");
+      assert.equal(readFileSync(fix.path, "utf-8"), before, "--fix must not rewrite a draft it didn't change");
+    });
+  });
 });

From d17439d6b7a6a45184444de5a023e48dfa1801d4 Mon Sep 17 00:00:00 2001
From: Rene Zander <renezander030@gmail.com>
Date: Wed, 8 Jul 2026 10:27:20 +0000
Subject: [PATCH 10/17] fix(sync-timelines): direction safety, exact write set,
 honest verdicts

- Direction hazard: plan now reports each target's mtime plus
  canonical_stale/newer_mirrors, warns when draft_content.json is older
  than a drifted mirror (CapCut >= 8.7 writes mirrors on save), and
  --apply refuses that direction unless --force-write. diagnose's
  divergence advice recommends the plan form with a back-up caution
  instead of a destructive --apply one-liner.
- Custom-file scope: input is restricted to a project directory or its
  draft_content.json path; any other explicitly named draft file exits 1
  with a pointer to the directory form, symmetrically for plan and
  --apply, so the plan and the write always cover the same target set.
- Write set: --apply writes exactly the drifted mirrors via the factored
  commitDraftTargets/assertTargetsUnchangedOnDisk helpers (atomic
  temp+rename, .bak per file written, changed-on-disk guard between plan
  read and write). draft_content.json is never rewritten (no sortTracks
  reorder, no canonical .bak overwrite) and in-sync mirrors stay
  untouched; JSON reconciled/backups list only files actually written.
- --apply --dry-run no longer prints 'Reconciled ...' on stderr; it
  states plan-only and reports would_reconcile with reconciled: [].
- Unreconcilable honesty: apply and the in-sync report now compute
  ok/in_sync the same way and exit 2 while a readable-by-CapCut mirror
  cannot be reconciled, so re-runs on unchanged state repeat the verdict.
---
 src/command-specs.ts         |   9 +-
 src/draft.ts                 |  79 +++++++++------
 src/index.ts                 | 130 +++++++++++++++++-------
 src/store.ts                 |  83 +++++++++++----
 test/sync-timelines.test.mjs | 190 +++++++++++++++++++++++++++++++++--
 5 files changed, 395 insertions(+), 96 deletions(-)

diff --git a/src/command-specs.ts b/src/command-specs.ts
index 26ae987..95a2889 100644
--- a/src/command-specs.ts
+++ b/src/command-specs.ts
@@ -185,7 +185,7 @@ const usages = {
   doctor: "capcut doctor",
   diagnose: "capcut diagnose <project> [--bundle <report.json>]",
   fixture: "capcut fixture <project> --out <dir>",
-  "sync-timelines": "capcut sync-timelines <project> [--apply]",
+  "sync-timelines": "capcut sync-timelines <project-dir> [--apply]",
   restore: "capcut restore <project> [--step <number> | --list]",
   serve: "capcut serve [--queue <path>] [options]",
   decrypt: "capcut decrypt <project-or-file>",
@@ -361,7 +361,12 @@ const optionsByCommand: Record<string, OptionSpec[]> = {
   diagnose: [option("bundle", ["--bundle"], "path", "Write a redacted JSON diagnostic bundle.")],
   fixture: [option("out", ["--out"], "path", "Output directory for the sanitized bundle.")],
   "sync-timelines": [
-    option("apply", ["--apply"], "boolean", "Write the reconciled timelines (default: print the plan only)."),
+    option(
+      "apply",
+      ["--apply"],
+      "boolean",
+      "Rewrite only the drifted mirror files from draft_content.json (default: print the plan only).",
+    ),
   ],
   "replace-media": [
     option("retime", ["--retime"], "boolean", "Fit the segment to the new clip instead of preserving in/out."),
diff --git a/src/draft.ts b/src/draft.ts
index 390d5d1..af7dd2d 100644
--- a/src/draft.ts
+++ b/src/draft.ts
@@ -14,6 +14,7 @@ import {
 } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import {
+  type DraftCandidate,
   type DraftStore,
   discoverDraftStore,
   editorProcesses,
@@ -217,47 +218,32 @@ export function listSnapshots(filePath: string): Array<{ step: number; index: nu
     .map((s, i) => ({ step: i + 1, index: s.index, path: s.path }));
 }
 
-export function saveDraft(filePath: string, draft: Draft, options: { backup?: boolean } = {}): void {
-  if (dryRun) {
-    // Normalize in memory (so any read-back is consistent) but write nothing.
-    sortTracks(draft);
-    return;
-  }
-
-  const resolved = resolve(filePath);
-  const context = loadContexts.get(resolved) ?? { store: discoverDraftStore(filePath) };
-  const { store } = context;
-
-  if (!forceWrite && isManagedDraftPath(filePath)) {
-    const running = editorProcesses();
-    if (running.length > 0) {
+// Optimistic concurrency check: never silently overwrite a file changed by
+// CapCut, another CLI process, or a sync client since the candidates were read.
+export function assertTargetsUnchangedOnDisk(targets: DraftCandidate[]): void {
+  for (const target of targets) {
+    if (!target.exists || target.raw === null) continue;
+    const current = readFileSync(target.path, "utf-8");
+    if (current !== target.raw) {
       throw new Error(
-        `${running.join(" / ")} is running. Close the editor before writing this managed draft, ` +
-          "or pass --force-write if you accept that the app may overwrite the change.",
+        `Draft changed on disk after it was loaded: ${target.name}. ` +
+          "Reload and retry, or pass --force-write to overwrite intentionally.",
       );
     }
   }
+}
 
-  // Optimistic concurrency check: never silently overwrite a file changed by
-  // CapCut, another CLI process, or a sync client since loadDraft read it.
-  if (!forceWrite) {
-    for (const target of store.targets) {
-      if (!target.exists || target.raw === null) continue;
-      const current = readFileSync(target.path, "utf-8");
-      if (current !== target.raw) {
-        throw new Error(
-          `Draft changed on disk after it was loaded: ${target.name}. ` +
-            "Reload and retry, or pass --force-write to overwrite intentionally.",
-        );
-      }
-    }
-  }
-
-  sortTracks(draft);
+// Transactional multi-target write: serialize `draft` into each target's own
+// envelope, then temp+fsync+rename with a `.bak` (and history snapshot) per
+// file actually written, rolling back on a partial commit. Writes EXACTLY the
+// given targets — callers decide the write set (saveDraft: every readable
+// sibling; sync-timelines: only the drifted mirrors). No-ops under --dry-run.
+export function commitDraftTargets(targets: DraftCandidate[], draft: Draft, options: { backup?: boolean } = {}): void {
+  if (dryRun) return;
 
   // Prepare every replacement before renaming any target. This keeps the
   // multi-file write as close to a transaction as the filesystem allows.
-  const prepared = store.targets.map((target, index) => {
+  const prepared = targets.map((target, index) => {
     const content = serializeDraftCandidate(target, draft);
     const temp = `${target.path}.capcut-cli-${process.pid}-${Date.now()}-${index}.tmp`;
     writeAndSync(temp, content);
@@ -286,6 +272,33 @@ export function saveDraft(filePath: string, draft: Draft, options: { backup?: bo
     }
     throw error;
   }
+}
+
+export function saveDraft(filePath: string, draft: Draft, options: { backup?: boolean } = {}): void {
+  if (dryRun) {
+    // Normalize in memory (so any read-back is consistent) but write nothing.
+    sortTracks(draft);
+    return;
+  }
+
+  const resolved = resolve(filePath);
+  const context = loadContexts.get(resolved) ?? { store: discoverDraftStore(filePath) };
+  const { store } = context;
+
+  if (!forceWrite && isManagedDraftPath(filePath)) {
+    const running = editorProcesses();
+    if (running.length > 0) {
+      throw new Error(
+        `${running.join(" / ")} is running. Close the editor before writing this managed draft, ` +
+          "or pass --force-write if you accept that the app may overwrite the change.",
+      );
+    }
+  }
+
+  if (!forceWrite) assertTargetsUnchangedOnDisk(store.targets);
+
+  sortTracks(draft);
+  commitDraftTargets(store.targets, draft, options);
 
   // Refresh hashes/raw snapshots so a library caller can save the same loaded
   // draft more than once without tripping its own conflict guard.
diff --git a/src/index.ts b/src/index.ts
index 4ca520f..6b4463c 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -39,6 +39,8 @@ import { detectEncryption } from "./decrypt.js";
 import { type DoctorCheck, draftDirs, runDoctor } from "./doctor.js";
 import type { Draft, Segment, Track } from "./draft.js";
 import {
+  assertTargetsUnchangedOnDisk,
+  commitDraftTargets,
   extractStyleRanges,
   extractText,
   findDraft,
@@ -319,11 +321,17 @@ Maintenance & inspection:
   fixture    <project> --out <dir>              Build a shareable, redacted compatibility bundle
              (timeline JSON only, no media; home paths + emails redacted) to
              attach to a version-support issue like #35.
-  sync-timelines <project> [--apply]            Reconcile timeline mirrors (template-2.tmp,
+  sync-timelines <project-dir> [--apply]        Reconcile timeline mirrors (template-2.tmp,
              draft_info.json) that drifted from draft_content.json, so a CLI
-             edit is honored by CapCut >= 8.7 (issue #35). Prints the plan by
-             default; writes only with --apply. Refuses to write while the
-             editor is running unless --force-write.
+             edit is honored by CapCut >= 8.7 (issue #35). Prints the plan
+             (with each file's mtime) by default; --apply rewrites ONLY the
+             drifted mirrors — draft_content.json and in-sync mirrors are
+             never touched — with a .bak per file written. Refuses to write
+             while the editor is running, or when draft_content.json is older
+             than a drifted mirror (the app may have saved newer edits there),
+             unless --force-write. Accepts the project directory or its
+             draft_content.json path. Exits 2 when a mirror exists that the
+             CLI cannot reconcile (binary/encrypted template-2.tmp).
 
 Animate:
   keyframe   <project> <id> <property> <time> <value> [--easing <name>]
@@ -2512,12 +2520,17 @@ function cmdDiagnose(projectPath: string | undefined, flags: Flags): void {
 // `sync-timelines` repairs a draft whose mirror files (template-2.tmp /
 // draft_info.json — including the pre-open mirror's stale GUID) drifted from
 // draft_content.json, the CapCut >= 8.7 "CLI edit silently ignored" failure
-// (issue #35 / #39). draft_content.json is canonical; the write reuses
-// saveDraft so every readable target is rewritten transactionally inside its
-// own envelope. Plan-only by default; --apply writes.
-function cmdSyncTimelines(projectPath: string | undefined, flags: Flags): void {
-  if (!projectPath) die("Usage: capcut sync-timelines <project> [--apply] [--force-write]");
-  const plan = planTimelineSync(projectPath);
+// (issue #35 / #39). draft_content.json is canonical and treated as a
+// read-only source: --apply rewrites EXACTLY the drifted mirrors inside their
+// own envelopes (atomic temp+rename, one .bak per file written) and never
+// touches draft_content.json or in-sync mirrors. Because CapCut >= 8.7 writes
+// the mirrors on save, a canonical file OLDER than a drifted mirror may mean
+// the mirror holds newer app edits — --apply refuses that direction unless
+// --force-write. Plan-only by default; --apply writes. Returns the exit code:
+// 0 ok, 1 via die(), 2 when a mirror exists that the CLI cannot reconcile.
+function cmdSyncTimelines(projectPath: string | undefined, flags: Flags): number {
+  if (!projectPath) die("Usage: capcut sync-timelines <project-dir> [--apply] [--force-write]");
+  const { plan, canonicalDraft, canonicalCandidate, driftedCandidates } = planTimelineSync(projectPath);
 
   const warnUnreconcilable = (): void => {
     if (flags.quiet) return;
@@ -2525,31 +2538,49 @@ function cmdSyncTimelines(projectPath: string | undefined, flags: Flags): void {
       process.stderr.write(`WARNING ${u.file}: ${u.reason}. ${u.workaround}\n`);
     }
   };
+  const staleCanonicalWarning = (): string => {
+    const canonicalTarget = plan.targets.find((target) => target.state === "canonical");
+    const newer = plan.targets
+      .filter((target) => plan.newer_mirrors.includes(target.file))
+      .map((target) => `${target.file} (${target.mtime})`)
+      .join(", ");
+    return (
+      `draft_content.json (${canonicalTarget?.mtime}) is OLDER than the drifted mirror(s) ${newer}. ` +
+      "CapCut >= 8.7 writes these mirrors on save, so they may hold newer app edits that this repair would roll back."
+    );
+  };
 
   if (plan.in_sync) {
-    const message =
-      plan.unreconcilable.length === 0
-        ? "All readable timeline targets already agree — nothing to write."
-        : `Readable timeline targets agree, but ${plan.unreconcilable.map((u) => u.file).join(", ")} cannot be reconciled by the CLI — see unreconcilable.`;
-    out({ ok: plan.unreconcilable.length === 0, applied: false, message, ...plan }, flags);
+    const ok = plan.unreconcilable.length === 0;
+    const message = ok
+      ? "All readable timeline targets already agree — nothing to write."
+      : `Readable timeline targets agree, but ${plan.unreconcilable.map((u) => u.file).join(", ")} cannot be reconciled by the CLI — see unreconcilable.`;
+    out({ ok, applied: false, message, ...plan, in_sync: ok }, flags);
     if (!flags.quiet) process.stderr.write(`${message}\n`);
     warnUnreconcilable();
-    return;
+    return ok ? 0 : 2;
   }
 
   if (!flags.apply) {
     const message = `Would rewrite ${plan.drifted.join(", ")} from draft_content.json. Re-run with --apply to write.`;
     out({ ok: true, applied: false, message, ...plan }, flags);
     if (!flags.quiet) {
+      const canonicalTarget = plan.targets.find((target) => target.state === "canonical");
+      process.stderr.write(`plan: canonical draft_content.json (mtime ${canonicalTarget?.mtime})\n`);
       for (const target of plan.targets) {
         if (target.state !== "drifted") continue;
         const guidNote = target.guid_drifted ? ` [stale GUID ${target.guid} -> canonical]` : "";
-        process.stderr.write(`plan: rewrite ${target.file} (envelope: ${target.envelope})${guidNote}\n`);
+        process.stderr.write(
+          `plan: rewrite ${target.file} (envelope: ${target.envelope}, mtime ${target.mtime})${guidNote}\n`,
+        );
+      }
+      if (plan.canonical_stale) {
+        process.stderr.write(`WARNING: ${staleCanonicalWarning()} --apply will refuse without --force-write.\n`);
       }
       warnUnreconcilable();
       process.stderr.write("Plan only — re-run with --apply to write.\n");
     }
-    return;
+    return 0;
   }
 
   if (!flags.forceWrite) {
@@ -2560,35 +2591,65 @@ function cmdSyncTimelines(projectPath: string | undefined, flags: Flags): void {
           "or pass --force-write if you accept that the app may overwrite the change.",
       );
     }
-  }
-
-  const { draft, filePath } = loadDraft(plan.canonical_path);
-  saveDraft(filePath, draft); // no-ops under --dry-run
-
-  if (!isDryRun()) {
-    const verify = planTimelineSync(projectPath);
-    if (!verify.in_sync) {
+    if (plan.canonical_stale) {
       die(
-        `sync-timelines wrote the targets but they still diverge (${verify.drifted.join(", ")}). ` +
-          "Restore from the .bak files and report this.",
+        `${staleCanonicalWarning()} Back up the project, review the plan (capcut sync-timelines ${projectPath}), ` +
+          "and pass --force-write only if draft_content.json is really the timeline you want to keep.",
       );
     }
   }
+
+  if (isDryRun()) {
+    const message = `Dry run — plan only. Would rewrite ${plan.drifted.join(", ")} from draft_content.json; nothing was written.`;
+    out(
+      {
+        ok: true,
+        applied: false,
+        message,
+        project_dir: plan.project_dir,
+        canonical: plan.canonical,
+        would_reconcile: plan.drifted,
+        reconciled: [],
+        backups: [],
+        unreconcilable: plan.unreconcilable,
+        in_sync: false,
+      },
+      flags,
+    );
+    if (!flags.quiet) process.stderr.write(`${message}\n`);
+    warnUnreconcilable();
+    return 0;
+  }
+
+  // Optimistic concurrency: neither the canonical source nor a mirror we are
+  // about to rewrite may have changed on disk between the plan read and now.
+  if (!flags.forceWrite) assertTargetsUnchangedOnDisk([canonicalCandidate, ...driftedCandidates]);
+  commitDraftTargets(driftedCandidates, canonicalDraft);
+
+  const verify = planTimelineSync(projectPath);
+  if (!verify.plan.in_sync) {
+    die(
+      `sync-timelines wrote the targets but they still diverge (${verify.plan.drifted.join(", ")}). ` +
+        "Restore from the .bak files and report this.",
+    );
+  }
+  const ok = plan.unreconcilable.length === 0;
   out(
     {
-      ok: true,
-      applied: !isDryRun(),
+      ok,
+      applied: true,
       project_dir: plan.project_dir,
       canonical: plan.canonical,
       reconciled: plan.drifted,
-      backups: isDryRun() ? [] : plan.drifted.map((file) => `${file}.bak`),
+      backups: plan.drifted.map((file) => `${file}.bak`),
       unreconcilable: plan.unreconcilable,
-      in_sync: !isDryRun(),
+      in_sync: ok,
     },
     flags,
   );
   if (!flags.quiet) process.stderr.write(`Reconciled from draft_content.json: ${plan.drifted.join(", ")}\n`);
   warnUnreconcilable();
+  return ok ? 0 : 2;
 }
 
 function cmdTemplates(flags: Flags): void {
@@ -2930,7 +2991,7 @@ const SUMMARIES: Record<string, string> = {
   doctor: "Environment preflight (Node, whisper, API key, project dir).",
   diagnose: "Inspect canonical draft files, divergence, and editor-write safety.",
   "sync-timelines":
-    "Reconcile timeline mirrors (template-2.tmp, draft_info.json) drifted from draft_content.json (plan by default; --apply writes).",
+    "Reconcile drifted timeline mirrors (template-2.tmp, draft_info.json) from a read-only draft_content.json (plan with mtimes by default; --apply rewrites only the drifted mirrors).",
   prune: "Remove materials no segment references.",
   relink: "Repair broken media paths (--dir or --from/--to).",
   timeline: "Show the track/segment layout (JSON, or -H ASCII bars).",
@@ -3361,8 +3422,7 @@ async function main(): Promise<void> {
   // `sync-timelines` must see drifted/unreadable siblings itself — loadDraft would
   // pick template-2.tmp as canonical on modern storage, the opposite of the repair.
   if (cmd === "sync-timelines") {
-    cmdSyncTimelines(projectPath, flags);
-    process.exit(0);
+    process.exit(cmdSyncTimelines(projectPath, flags));
   }
 
   // `restore` copies a backup/snapshot back over the draft — no loadDraft/parse needed.
diff --git a/src/store.ts b/src/store.ts
index f2ac24d..c77da9e 100644
--- a/src/store.ts
+++ b/src/store.ts
@@ -2,7 +2,7 @@ import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { platform } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import type { Draft } from "./draft.js";
 
 const STANDARD_FILES = ["draft_content.json", "draft_info.json", "draft_meta_info.json", "template-2.tmp"] as const;
@@ -291,6 +291,7 @@ export interface TimelineSyncTarget {
   file: string;
   state: "canonical" | "in_sync" | "drifted";
   envelope: string;
+  mtime: string | null;
   timeline_hash: string | null;
   guid: string | null;
   guid_drifted: boolean;
@@ -311,16 +312,29 @@ export interface TimelineSyncPlan {
   version: string | null;
   modern_storage: boolean;
   in_sync: boolean;
+  /** Drifted mirrors whose mtime is newer than draft_content.json's. CapCut
+   * >= 8.7 writes the mirrors on save, so a newer drifted mirror may hold app
+   * edits that a canonical -> mirror repair would roll back. */
+  newer_mirrors: string[];
+  canonical_stale: boolean;
   targets: TimelineSyncTarget[];
   drifted: string[];
   unreconcilable: TimelineSyncUnreconcilable[];
 }
 
+export interface TimelineSyncResult {
+  plan: TimelineSyncPlan;
+  canonicalDraft: Draft;
+  canonicalCandidate: DraftCandidate;
+  driftedCandidates: DraftCandidate[];
+}
+
 function syncTarget(candidate: DraftCandidate, state: TimelineSyncTarget["state"], guidDrifted: boolean) {
   return {
     file: candidate.name,
     state,
     envelope: candidate.envelopePath.length === 0 ? "root" : candidate.envelopePath.join("."),
+    mtime: candidate.mtime,
     timeline_hash: candidate.timelineHash,
     guid: candidate.draft?.id ?? null,
     guid_drifted: guidDrifted,
@@ -332,13 +346,25 @@ function syncTarget(candidate: DraftCandidate, state: TimelineSyncTarget["state"
 /**
  * Plan for `sync-timelines` (issue #39, symptom #35): draft_content.json is
  * canonical; every other readable timeline target is compared against it by
- * timeline hash. Direction is always draft_content.json -> mirror, never
- * inferred from mtimes (copy tools and sync clients rewrite those). A mirror
- * file that exists but holds no readable timeline (binary/encrypted
- * template-2.tmp) cannot be reconciled and is reported as such instead of
- * being silently skipped.
+ * timeline hash. Direction is always draft_content.json -> mirror, but each
+ * target's mtime is surfaced: CapCut >= 8.7 writes the mirrors on save, so a
+ * drifted mirror NEWER than draft_content.json may hold app edits that the
+ * repair would roll back (canonical_stale / newer_mirrors flag this; --apply
+ * refuses without --force-write). A mirror file that exists but holds no
+ * readable timeline (binary/encrypted template-2.tmp) cannot be reconciled
+ * and is reported as such instead of being silently skipped. Accepts a
+ * project directory or its draft_content.json path; any other explicitly
+ * named file is rejected so the plan and the write always cover the same
+ * target set.
  */
-export function planTimelineSync(input: string): TimelineSyncPlan {
+export function planTimelineSync(input: string): TimelineSyncResult {
+  const resolved = resolve(input);
+  if (existsSync(resolved) && statSync(resolved).isFile() && basename(resolved) !== "draft_content.json") {
+    throw new Error(
+      `sync-timelines reconciles a project's mirror files from draft_content.json and cannot target ${basename(resolved)} directly. ` +
+        `Pass the project directory instead: capcut sync-timelines ${dirname(resolved)}`,
+    );
+  }
   const store = discoverDraftStore(input);
   const canonical = store.targets.find((candidate) => candidate.name === "draft_content.json");
   if (!canonical?.draft) {
@@ -347,9 +373,13 @@ export function planTimelineSync(input: string): TimelineSyncPlan {
         "Run `capcut diagnose <project>` to inspect what is on disk.",
     );
   }
+  const canonicalDraft = canonical.draft;
+  const canonicalMtime = canonical.mtime ? Date.parse(canonical.mtime) : Number.NaN;
 
   const targets: TimelineSyncTarget[] = [syncTarget(canonical, "canonical", false)];
   const drifted: string[] = [];
+  const driftedCandidates: DraftCandidate[] = [];
+  const newerMirrors: string[] = [];
   const unreconcilable: TimelineSyncUnreconcilable[] = [];
   for (const candidate of store.candidates) {
     if (!candidate.exists || candidate.path === canonical.path) continue;
@@ -366,20 +396,34 @@ export function planTimelineSync(input: string): TimelineSyncPlan {
       continue;
     }
     const inSync = candidate.timelineHash === canonical.timelineHash;
-    targets.push(syncTarget(candidate, inSync ? "in_sync" : "drifted", candidate.draft.id !== canonical.draft.id));
-    if (!inSync) drifted.push(candidate.name);
+    targets.push(syncTarget(candidate, inSync ? "in_sync" : "drifted", candidate.draft.id !== canonicalDraft.id));
+    if (!inSync) {
+      drifted.push(candidate.name);
+      driftedCandidates.push(candidate);
+      const mirrorMtime = candidate.mtime ? Date.parse(candidate.mtime) : Number.NaN;
+      if (Number.isFinite(canonicalMtime) && Number.isFinite(mirrorMtime) && mirrorMtime > canonicalMtime) {
+        newerMirrors.push(candidate.name);
+      }
+    }
   }
 
   return {
-    project_dir: store.projectDir,
-    canonical: canonical.name,
-    canonical_path: canonical.path,
-    version: store.version,
-    modern_storage: store.modernStorage,
-    in_sync: drifted.length === 0,
-    targets,
-    drifted,
-    unreconcilable,
+    plan: {
+      project_dir: store.projectDir,
+      canonical: canonical.name,
+      canonical_path: canonical.path,
+      version: store.version,
+      modern_storage: store.modernStorage,
+      in_sync: drifted.length === 0,
+      newer_mirrors: newerMirrors,
+      canonical_stale: newerMirrors.length > 0,
+      targets,
+      drifted,
+      unreconcilable,
+    },
+    canonicalDraft,
+    canonicalCandidate: canonical,
+    driftedCandidates,
   };
 }
 
@@ -389,7 +433,8 @@ export function diagnoseDraftStore(input: string): DraftStoreReport {
   const actions: string[] = [];
   if (store.diverged)
     actions.push(
-      "Timeline files diverge. Close CapCut, then run `capcut sync-timelines <project> --apply` to reconcile them from draft_content.json.",
+      "Timeline files diverge. Close CapCut and back up the project folder, then run `capcut sync-timelines <project>` " +
+        "(plan only) to review each file's mtime and the write targets before deciding whether to --apply.",
     );
   if (store.modernStorage && !store.targets.some((candidate) => candidate.name === "template-2.tmp")) {
     actions.push(
diff --git a/test/sync-timelines.test.mjs b/test/sync-timelines.test.mjs
index 10faddf..e0d8878 100644
--- a/test/sync-timelines.test.mjs
+++ b/test/sync-timelines.test.mjs
@@ -1,10 +1,20 @@
 import assert from "node:assert/strict";
 import { spawn } from "node:child_process";
-import { chmodSync, copyFileSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import {
+  chmodSync,
+  copyFileSync,
+  existsSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  utimesSync,
+  writeFileSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { after, describe, it } from "node:test";
-import { editorProcesses } from "../dist/store.js";
+import { assertTargetsUnchangedOnDisk } from "../dist/draft.js";
+import { editorProcesses, planTimelineSync } from "../dist/store.js";
 import { spawnCli } from "./helpers/spawn-cli.mjs";
 
 // The canonical timeline: what the CLI wrote to draft_content.json (issue #35:
@@ -38,11 +48,28 @@ function staleDraft() {
 
 // Drift fixture: draft_content.json is canonical/newer; template-2.tmp (string-
 // JSON envelope) and draft_info.json (root envelope) still hold the old timeline.
+// The mirrors' mtimes are set into the past to model the issue-#35 scenario the
+// repair exists for: the CLI edited draft_content.json AFTER the app last wrote
+// the mirrors.
 function driftedFixture() {
   const dir = mkdtempSync(join(tmpdir(), "capcut-sync-"));
   writeFileSync(join(dir, "draft_content.json"), JSON.stringify(canonicalDraft(), null, 2));
   writeFileSync(join(dir, "template-2.tmp"), JSON.stringify({ draft_content: JSON.stringify(staleDraft()) }, null, 2));
   writeFileSync(join(dir, "draft_info.json"), JSON.stringify(staleDraft(), null, 2));
+  const past = new Date(Date.now() - 3_600_000);
+  utimesSync(join(dir, "template-2.tmp"), past, past);
+  utimesSync(join(dir, "draft_info.json"), past, past);
+  return { dir, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
+}
+
+// Direction-hazard fixture: the drifted mirror is NEWER than draft_content.json
+// (the CapCut >= 8.7 app wrote it on save after the canonical file went stale).
+function staleCanonicalFixture() {
+  const dir = mkdtempSync(join(tmpdir(), "capcut-sync-"));
+  writeFileSync(join(dir, "draft_content.json"), JSON.stringify(canonicalDraft(), null, 2));
+  writeFileSync(join(dir, "draft_info.json"), JSON.stringify(staleDraft(), null, 2));
+  const past = new Date(Date.now() - 3_600_000);
+  utimesSync(join(dir, "draft_content.json"), past, past);
   return { dir, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
 }
 
@@ -62,7 +89,12 @@ describe("sync-timelines", () => {
     const info = r.json.targets.find((t) => t.file === "draft_info.json");
     assert.equal(info.state, "drifted");
     assert.equal(info.guid_drifted, true, "the pre-open mirror's stale GUID must be flagged");
+    for (const target of r.json.targets) {
+      assert.equal(typeof target.mtime, "string", `${target.file} must report its mtime`);
+    }
+    assert.equal(r.json.canonical_stale, false, "mirrors older than draft_content.json are the normal direction");
     assert.match(r.stderr, /--apply/);
+    assert.match(r.stderr, /mtime/, "the human plan must surface mtimes");
     assert.equal(readFileSync(join(f.dir, "template-2.tmp"), "utf-8"), tmpBefore, "plan must not write");
     assert.equal(readFileSync(join(f.dir, "draft_info.json"), "utf-8"), infoBefore, "plan must not write");
   });
@@ -110,7 +142,7 @@ describe("sync-timelines", () => {
     assert.match(r.stderr, /already agree/);
   });
 
-  it("--apply --dry-run previews without writing", () => {
+  it("--apply --dry-run previews without writing and does not claim reconciliation", () => {
     const f = driftedFixture();
     after(f.cleanup);
     const infoBefore = readFileSync(join(f.dir, "draft_info.json"), "utf-8");
@@ -119,7 +151,14 @@ describe("sync-timelines", () => {
     assert.equal(r.status, 0, `stderr: ${r.stderr}`);
     assert.equal(r.json.dryRun, true);
     assert.equal(r.json.applied, false);
+    assert.deepEqual(r.json.reconciled, [], "dry-run must not claim reconciliation");
+    assert.deepEqual(r.json.backups, []);
+    assert.deepEqual(r.json.would_reconcile.sort(), ["draft_info.json", "template-2.tmp"]);
+    assert.equal(r.json.in_sync, false);
+    assert.doesNotMatch(r.stderr, /Reconciled/, "dry-run stderr must not assert a repair happened");
+    assert.match(r.stderr, /plan only/i);
     assert.equal(readFileSync(join(f.dir, "draft_info.json"), "utf-8"), infoBefore, "dry-run must not write");
+    assert.ok(!existsSync(join(f.dir, "draft_info.json.bak")), "dry-run must not create backups");
   });
 
   it("reports an unreadable template-2.tmp as unreconcilable instead of pretending success", () => {
@@ -136,7 +175,10 @@ describe("sync-timelines", () => {
     assert.match(plan.stderr, /WARNING template-2\.tmp/);
 
     const r = spawnCli(["sync-timelines", f.dir, "--apply"]);
-    assert.equal(r.status, 0, `stderr: ${r.stderr}`);
+    assert.equal(r.status, 2, "an unreconcilable mirror must exit 2, not pretend success");
+    assert.equal(r.json.ok, false, "the file CapCut trusts may still hold the stale timeline");
+    assert.equal(r.json.in_sync, false, "in_sync must not be asserted when a mirror could not be reconciled");
+    assert.equal(r.json.applied, true);
     assert.deepEqual(r.json.reconciled, ["draft_info.json"], "only the readable mirror is repaired");
     assert.equal(r.json.unreconcilable[0].file, "template-2.tmp");
     assert.match(r.stderr, /WARNING template-2\.tmp/);
@@ -146,14 +188,148 @@ describe("sync-timelines", () => {
       "binary mirror left untouched",
     );
 
-    // The remaining unreconcilable mirror keeps ok=false honesty on later runs.
+    // Idempotent verdict: a re-run on the unchanged state reports the same
+    // ok/in_sync/exit outcome as the apply that left it there.
     const again = spawnCli(["sync-timelines", f.dir]);
-    assert.equal(again.status, 0);
-    assert.equal(again.json.in_sync, true);
+    assert.equal(again.status, 2, "the unreconcilable state must keep reporting exit 2");
+    assert.equal(again.json.in_sync, false);
     assert.equal(again.json.ok, false, "an unreconcilable mirror must not be reported as fully ok");
     assert.match(again.json.message, /cannot be reconciled/);
   });
 
+  it("plan warns when draft_content.json is older than a drifted mirror", () => {
+    const f = staleCanonicalFixture();
+    after(f.cleanup);
+
+    const r = spawnCli(["sync-timelines", f.dir]);
+    assert.equal(r.status, 0, `stderr: ${r.stderr}`);
+    assert.equal(r.json.canonical_stale, true);
+    assert.deepEqual(r.json.newer_mirrors, ["draft_info.json"]);
+    for (const target of r.json.targets) {
+      assert.equal(typeof target.mtime, "string", `${target.file} must report its mtime`);
+    }
+    assert.match(r.stderr, /WARNING: draft_content\.json .* is OLDER/);
+    assert.match(r.stderr, /--force-write/);
+  });
+
+  it("--apply refuses to roll back a mirror newer than draft_content.json unless --force-write", () => {
+    const f = staleCanonicalFixture();
+    after(f.cleanup);
+    const infoBefore = readFileSync(join(f.dir, "draft_info.json"), "utf-8");
+
+    const refused = spawnCli(["sync-timelines", f.dir, "--apply"]);
+    assert.equal(refused.status, 1, "the older-canonical direction must refuse without --force-write");
+    assert.match(refused.stderr, /OLDER/);
+    assert.match(refused.stderr, /--force-write/);
+    assert.equal(readFileSync(join(f.dir, "draft_info.json"), "utf-8"), infoBefore, "refusal must not write");
+    assert.ok(!existsSync(join(f.dir, "draft_info.json.bak")), "refusal must not create backups");
+
+    const forced = spawnCli(["sync-timelines", f.dir, "--apply", "--force-write"]);
+    assert.equal(forced.status, 0, `stderr: ${forced.stderr}`);
+    assert.equal(JSON.parse(readFileSync(join(f.dir, "draft_info.json"), "utf-8")).id, "guid-canonical");
+  });
+
+  it("diagnose recommends the plan form with a back-up caution, never a blind --apply", () => {
+    const f = driftedFixture();
+    after(f.cleanup);
+
+    const r = spawnCli(["diagnose", f.dir]);
+    assert.equal(r.status, 0, `stderr: ${r.stderr}`);
+    const advice = r.json.next_actions.join(" ");
+    assert.match(advice, /back up/i, "divergence advice must retain a back-up caution");
+    assert.match(advice, /`capcut sync-timelines <project>`/, "divergence advice must recommend the plan form");
+    assert.ok(
+      !advice.includes("sync-timelines <project> --apply"),
+      "diagnose must not recommend a destructive one-liner",
+    );
+  });
+
+  it("rejects an explicitly named custom draft file, symmetrically for plan and --apply", () => {
+    const dir = mkdtempSync(join(tmpdir(), "capcut-sync-"));
+    after(() => rmSync(dir, { recursive: true, force: true }));
+    writeFileSync(join(dir, "draft_content.json"), JSON.stringify(canonicalDraft(), null, 2));
+    writeFileSync(join(dir, "A.json"), JSON.stringify(staleDraft(), null, 2));
+    writeFileSync(join(dir, "draft_info.json"), JSON.stringify(staleDraft(), null, 2));
+    const past = new Date(Date.now() - 3_600_000);
+    utimesSync(join(dir, "A.json"), past, past);
+    utimesSync(join(dir, "draft_info.json"), past, past);
+
+    const plan = spawnCli(["sync-timelines", join(dir, "A.json")]);
+    assert.equal(plan.status, 1);
+    assert.match(plan.stderr, /cannot target A\.json/);
+    assert.match(plan.stderr, /project directory/);
+
+    const apply = spawnCli(["sync-timelines", join(dir, "A.json"), "--apply"]);
+    assert.equal(apply.status, 1, "apply must reject the same inputs the plan rejects");
+    assert.match(apply.stderr, /cannot target A\.json/);
+    assert.equal(JSON.parse(readFileSync(join(dir, "A.json"), "utf-8")).id, "guid-mirror-stale");
+    assert.equal(JSON.parse(readFileSync(join(dir, "draft_info.json"), "utf-8")).id, "guid-mirror-stale");
+    assert.ok(!existsSync(join(dir, "A.json.bak")), "rejection must not write anything");
+    assert.ok(!existsSync(join(dir, "draft_info.json.bak")), "rejection must not write anything");
+
+    // The canonical file itself is an accepted alias for the directory form.
+    const accepted = spawnCli(["sync-timelines", join(dir, "draft_content.json")]);
+    assert.equal(accepted.status, 0, `stderr: ${accepted.stderr}`);
+    assert.deepEqual(accepted.json.drifted, ["draft_info.json"]);
+  });
+
+  it("--apply writes exactly the drifted mirrors: canonical and in-sync targets stay untouched", () => {
+    const dir = mkdtempSync(join(tmpdir(), "capcut-sync-"));
+    after(() => rmSync(dir, { recursive: true, force: true }));
+    // Canonical draft with tracks deliberately NOT in the CLI's TRACK_RANK
+    // order ([text, video]); the repair must copy it verbatim, not re-sort it.
+    const draft = canonicalDraft();
+    draft.tracks = [
+      { id: "T1", type: "text", name: "text", attribute: 0, segments: [] },
+      { id: "V1", type: "video", name: "video", attribute: 0, segments: [] },
+    ];
+    writeFileSync(join(dir, "draft_content.json"), JSON.stringify(draft, null, 2));
+    // In-sync mirror: the same timeline inside its envelope.
+    writeFileSync(join(dir, "template-2.tmp"), JSON.stringify({ draft_content: JSON.stringify(draft) }, null, 2));
+    // Drifted mirror, older than the canonical file.
+    writeFileSync(join(dir, "draft_info.json"), JSON.stringify(staleDraft(), null, 2));
+    const past = new Date(Date.now() - 3_600_000);
+    utimesSync(join(dir, "draft_info.json"), past, past);
+    // Pre-existing restore points the repair must not destroy.
+    writeFileSync(join(dir, "draft_content.json.bak"), "canonical-restore-point");
+    writeFileSync(join(dir, "template-2.tmp.bak"), "insync-restore-point");
+    const canonicalBefore = readFileSync(join(dir, "draft_content.json"), "utf-8");
+    const templateBefore = readFileSync(join(dir, "template-2.tmp"), "utf-8");
+
+    const r = spawnCli(["sync-timelines", dir, "--apply"]);
+    assert.equal(r.status, 0, `stderr: ${r.stderr}`);
+    assert.deepEqual(r.json.reconciled, ["draft_info.json"]);
+    assert.deepEqual(r.json.backups, ["draft_info.json.bak"], "backups must list only files actually written");
+    // draft_content.json is a read-only source: byte-identical, no track re-sort.
+    assert.equal(readFileSync(join(dir, "draft_content.json"), "utf-8"), canonicalBefore, "canonical rewritten");
+    assert.deepEqual(
+      JSON.parse(readFileSync(join(dir, "draft_content.json"), "utf-8")).tracks.map((t) => t.type),
+      ["text", "video"],
+      "the canonical track order must survive --apply",
+    );
+    // In-sync mirror untouched; the drifted mirror received the canonical timeline as-is.
+    assert.equal(readFileSync(join(dir, "template-2.tmp"), "utf-8"), templateBefore, "in-sync mirror rewritten");
+    const info = JSON.parse(readFileSync(join(dir, "draft_info.json"), "utf-8"));
+    assert.equal(info.id, "guid-canonical");
+    assert.deepEqual(
+      info.tracks.map((t) => t.type),
+      ["text", "video"],
+    );
+    // Pre-existing restore points survive; only the written mirror got a new .bak.
+    assert.equal(readFileSync(join(dir, "draft_content.json.bak"), "utf-8"), "canonical-restore-point");
+    assert.equal(readFileSync(join(dir, "template-2.tmp.bak"), "utf-8"), "insync-restore-point");
+    assert.ok(readFileSync(join(dir, "draft_info.json.bak"), "utf-8").includes("before-cli-edit"));
+  });
+
+  it("apply's concurrency guard rejects files changed between the plan read and the write", () => {
+    const f = driftedFixture();
+    after(f.cleanup);
+    const { canonicalCandidate, driftedCandidates } = planTimelineSync(f.dir);
+    const contentPath = join(f.dir, "draft_content.json");
+    writeFileSync(contentPath, `${readFileSync(contentPath, "utf-8")}\n`);
+    assert.throws(() => assertTargetsUnchangedOnDisk([canonicalCandidate, ...driftedCandidates]), /changed on disk/);
+  });
+
   it("errors when draft_content.json is missing (no canonical source)", () => {
     const dir = mkdtempSync(join(tmpdir(), "capcut-sync-"));
     after(() => rmSync(dir, { recursive: true, force: true }));

From 8f7874e7745e7f6c0212c1017b817135f47a6e79 Mon Sep 17 00:00:00 2001
From: Rene Zander <renezander030@gmail.com>
Date: Wed, 8 Jul 2026 10:34:50 +0000
Subject: [PATCH 11/17] fix(srt): karaoke collapse per repetition, ms rollover
 carry, valid WebVTT output

- collapseKaraokeRuns grouped runs purely by text equality, so a karaoke
  phrase repeated back-to-back merged into one 2N-segment run, failed
  word tiling, and word mode exploded each word segment into the full
  phrase (8 cues instead of 4 in the reviewed repro). Runs now require
  word-tiling validity: highlight ranges must tile the phrase words in
  order exactly once, and a range-cycle restart begins a new run, so
  each repetition collapses into its own cue with real word timings.
- Karaoke-shaped segments that fail run validation (out-of-order starts,
  partial runs) but highlight exactly one word keep that word with the
  segment's own timing; word mode never re-interpolates the full phrase
  into a single word's timeslot. Lone captions that merely emphasize a
  word still interpolate as before.
- srtTime rounded the sub-second fraction to milliseconds without
  carrying, emitting invalid timestamps like 00:00:01,1000 (and vttTime
  00:00:01.1000, which WebVTT parsers reject) for fractions >= 999.5ms.
  Rounding now happens on total milliseconds so the carry propagates
  through seconds, minutes and hours.
- Inline WebVTT karaoke timestamps are now strictly increasing and
  strictly greater than the cue start: a word whose start collides with
  the previous timestamp (coincident Whisper words) joins the previous
  timestamp group instead of emitting a spec-invalid duplicate tag.
- WebVTT cue text escapes & < > (line and word mode) so captions
  containing markup characters are no longer swallowed as tags; SRT
  output stays raw. export-srt help notes the escaping.

Findings addressed:
1. Karaoke collapse merges adjacent identical phrases, then word mode
   explodes each word segment into the full phrase (N^2 wrong cues)
2. vttTime/srtTime millisecond rollover emits invalid timestamps like
   00:00:01.1000 (WebVTT parsers drop the cue)
3. karaokeWords accepts equal word start times, producing inline VTT
   timestamps equal to the cue start (invalid per WebVTT spec)
4. renderVtt does not escape '&' and '<' in cue text
5. Word-level export silently garbles karaoke captions when a phrase
   repeats back-to-back (same root cause as 1)
---
 src/index.ts             |   3 +-
 src/srt.ts               | 141 ++++++++++++++++++++++++++----------
 src/time.ts              |  12 ++--
 test/export-srt.test.mjs | 150 ++++++++++++++++++++++++++++++++++++++-
 4 files changed, 260 insertions(+), 46 deletions(-)

diff --git a/src/index.ts b/src/index.ts
index 4ca520f..472892d 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -525,7 +525,8 @@ Subtitles (Phase 3):
                --granularity <line|word>  One cue per caption (default: line)
                                           or per word (karaoke).
                --format <srt|vtt>         SRT (default) or WebVTT. WebVTT word
-                                          cues use inline <timestamps>.
+                                          cues use inline <timestamps>; WebVTT
+                                          cue text escapes & < > as entities.
              Word timings are real where the draft stores them (caption
              --karaoke word segments); elsewhere they are interpolated within
              each cue, weighted by word character length.
diff --git a/src/srt.ts b/src/srt.ts
index 200893c..291fe05 100644
--- a/src/srt.ts
+++ b/src/srt.ts
@@ -98,76 +98,139 @@ export function cueWords(cue: SubtitleCue): SubtitleWord[] {
 // Karaoke captions (`caption --karaoke`) store one segment PER WORD: full
 // phrase text, word-timed segment, one style range highlighting that word.
 // A run of same-text segments whose highlighted ranges tile the phrase's
-// words in order collapses back into a single cue with real word timings.
+// words IN ORDER exactly once collapses back into a single cue with real
+// word timings. A phrase repeated back-to-back (chorus lines) yields the
+// same text 2N times; the highlight ranges cycle, and each cycle restart
+// begins a NEW run — one collapsed cue per repetition.
 export function collapseKaraokeRuns(entries: SegmentCue[]): SubtitleCue[] {
   const cues: SubtitleCue[] = [];
   let i = 0;
   while (i < entries.length) {
     let j = i + 1;
     while (j < entries.length && entries[j].text === entries[i].text) j++;
-    const run = entries.slice(i, j);
-    const words = karaokeWords(run);
-    if (words) {
-      cues.push({
-        startUs: run[0].startUs,
-        endUs: Math.max(...run.map((e) => e.endUs)),
-        text: run[0].text,
-        words,
-      });
-    } else {
-      for (const e of run) cues.push({ startUs: e.startUs, endUs: e.endUs, text: e.text });
-    }
+    collapseStretch(entries.slice(i, j), cues);
     i = j;
   }
   return cues;
 }
 
-function toUtf16Bytes(text: string, codeUnitIdx: number): number {
-  return Buffer.from(text.slice(0, codeUnitIdx), "utf16le").length;
+interface TokenRange {
+  word: string;
+  byteStart: number;
+  byteEnd: number;
 }
 
-function karaokeWords(run: SegmentCue[]): SubtitleWord[] | null {
-  if (run.length < 2) return null;
-  const text = run[0].text;
-  const tokens = [...text.matchAll(/\S+/g)];
-  if (tokens.length !== run.length) return null;
-  const words: SubtitleWord[] = [];
-  for (let k = 0; k < run.length; k++) {
-    const tok = tokens[k];
+function tokenRanges(text: string): TokenRange[] {
+  return [...text.matchAll(/\S+/g)].map((tok) => {
     const at = tok.index ?? 0;
-    const byteStart = toUtf16Bytes(text, at);
-    const byteEnd = toUtf16Bytes(text, at + tok[0].length);
-    const ranges = run[k].styleRanges ?? [];
-    if (!ranges.some((r) => r[0] === byteStart && r[1] === byteEnd)) return null;
-    if (k > 0 && run[k].startUs < run[k - 1].startUs) return null;
-    words.push({ word: tok[0], startUs: run[k].startUs, endUs: run[k].endUs });
+    return {
+      word: tok[0],
+      byteStart: toUtf16Bytes(text, at),
+      byteEnd: toUtf16Bytes(text, at + tok[0].length),
+    };
+  });
+}
+
+function matchesToken(entry: SegmentCue, tok: TokenRange): boolean {
+  return (entry.styleRanges ?? []).some((r) => r[0] === tok.byteStart && r[1] === tok.byteEnd);
+}
+
+// Collapse one maximal stretch of consecutive same-text segments. Greedy:
+// at each position, try to consume one full karaoke repetition (highlight
+// ranges matching token 0..n-1 in order, non-decreasing start times).
+// Segments that cannot join a valid run but still highlight exactly one
+// word keep that word's own timing — word mode must never re-interpolate
+// the full phrase into a single word's timeslot.
+function collapseStretch(stretch: SegmentCue[], cues: SubtitleCue[]): void {
+  const text = stretch[0].text;
+  const tokens = tokenRanges(text);
+  let i = 0;
+  while (i < stretch.length) {
+    if (tokens.length >= 2 && i + tokens.length <= stretch.length) {
+      let k = 0;
+      while (
+        k < tokens.length &&
+        matchesToken(stretch[i + k], tokens[k]) &&
+        (k === 0 || stretch[i + k].startUs >= stretch[i + k - 1].startUs)
+      ) {
+        k++;
+      }
+      if (k === tokens.length) {
+        const run = stretch.slice(i, i + k);
+        cues.push({
+          startUs: run[0].startUs,
+          endUs: Math.max(...run.map((e) => e.endUs)),
+          text,
+          words: run.map((e, w) => ({ word: tokens[w].word, startUs: e.startUs, endUs: e.endUs })),
+        });
+        i += k;
+        continue;
+      }
+    }
+    cues.push(orphanCue(stretch, stretch[i], tokens));
+    i++;
   }
-  return words;
+}
+
+// A same-text segment that did not fit a valid run. When the stretch is
+// karaoke-shaped (>= 2 same-text segments) and the segment highlights
+// exactly one word, keep that word as the segment's only timed word so
+// word-granularity export emits it once at its real time instead of
+// exploding the full phrase into the segment's timerange. A lone segment
+// (or one without a single-word highlight) stays an ordinary cue.
+function orphanCue(stretch: SegmentCue[], entry: SegmentCue, tokens: TokenRange[]): SubtitleCue {
+  const cue: SubtitleCue = { startUs: entry.startUs, endUs: entry.endUs, text: entry.text };
+  if (stretch.length < 2) return cue;
+  const matched = tokens.filter((tok) => matchesToken(entry, tok));
+  if (matched.length === 1) {
+    cue.words = [{ word: matched[0].word, startUs: entry.startUs, endUs: entry.endUs }];
+  }
+  return cue;
+}
+
+function toUtf16Bytes(text: string, codeUnitIdx: number): number {
+  return Buffer.from(text.slice(0, codeUnitIdx), "utf16le").length;
 }
 
 export function renderSrt(cues: Array<{ startUs: number; endUs: number; text: string }>): string {
   return cues.map((c, i) => `${i + 1}\n${srtTime(c.startUs)} --> ${srtTime(c.endUs)}\n${c.text}\n`).join("\n");
 }
 
+// WebVTT cue payload: '<' opens a tag and '&' a character reference, so raw
+// text must be escaped or everything after a bare '<' is swallowed. Applied
+// to cue text only — never to timing lines or inline timestamp tags.
+function vttEscape(text: string): string {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
 // Word granularity emits ONE cue per phrase with inline word timestamps
 // (`one <00:00:01.400>two`) — the karaoke form players understand. A leading
 // timestamp is omitted: the first word is active from the cue start.
 export function renderVtt(cues: SubtitleCue[], wordTimestamps: boolean): string {
   const blocks = cues.map((c) => {
-    const text = wordTimestamps ? vttKaraokeText(c) : c.text;
+    const text = wordTimestamps ? vttKaraokeText(c) : vttEscape(c.text);
     return `${vttTime(c.startUs)} --> ${vttTime(c.endUs)}\n${text}\n`;
   });
   return `WEBVTT\n\n${blocks.join("\n")}`;
 }
 
+// Inline timestamps must be strictly increasing and strictly greater than
+// the cue start (WebVTT spec), or players ignore the tag. Coincident word
+// starts (zero-duration Whisper words) share one timestamp group: the
+// duplicate tag is skipped and the word joins the previous group.
 function vttKaraokeText(cue: SubtitleCue): string {
   const words = cueWords(cue);
-  if (words.length === 0) return cue.text;
-  return (
-    words[0].word +
-    words
-      .slice(1)
-      .map((w) => ` <${vttTime(w.startUs)}>${w.word}`)
-      .join("")
-  );
+  if (words.length === 0) return vttEscape(cue.text);
+  let lastMs = Math.round(cue.startUs / 1000);
+  let text = vttEscape(words[0].word);
+  for (const w of words.slice(1)) {
+    const ms = Math.round(w.startUs / 1000);
+    if (ms > lastMs) {
+      text += ` <${vttTime(w.startUs)}>${vttEscape(w.word)}`;
+      lastMs = ms;
+    } else {
+      text += ` ${vttEscape(w.word)}`;
+    }
+  }
+  return text;
 }
diff --git a/src/time.ts b/src/time.ts
index 1c72826..92fff8f 100644
--- a/src/time.ts
+++ b/src/time.ts
@@ -68,11 +68,13 @@ function pad2(n: number): string {
 }
 
 export function srtTime(us: number): string {
-  const totalSec = us / US_PER_SEC;
-  const h = Math.floor(totalSec / 3600);
-  const m = Math.floor((totalSec % 3600) / 60);
-  const s = Math.floor(totalSec % 60);
-  const ms = Math.round((totalSec % 1) * 1000);
+  // Round to whole milliseconds FIRST so a fraction >= 999.5ms carries into
+  // seconds/minutes/hours instead of rendering an invalid ",1000" field.
+  const totalMs = Math.round(us / US_PER_MS);
+  const h = Math.floor(totalMs / 3_600_000);
+  const m = Math.floor((totalMs % 3_600_000) / 60_000);
+  const s = Math.floor((totalMs % 60_000) / 1000);
+  const ms = totalMs % 1000;
   return `${pad(h)}:${pad(m)}:${pad(s)},${ms.toString().padStart(3, "0")}`;
 }
 
diff --git a/test/export-srt.test.mjs b/test/export-srt.test.mjs
index 1ca59e9..0904ec2 100644
--- a/test/export-srt.test.mjs
+++ b/test/export-srt.test.mjs
@@ -1,7 +1,8 @@
 import assert from "node:assert/strict";
 import { join } from "node:path";
 import { after, before, describe, it } from "node:test";
-import { parseSrt } from "../dist/srt.js";
+import { collapseKaraokeRuns, parseSrt, renderVtt } from "../dist/srt.js";
+import { srtTime, vttTime } from "../dist/time.js";
 import { spawnCli } from "./helpers/spawn-cli.mjs";
 import { tmpDir } from "./helpers/tmp-draft.mjs";
 
@@ -117,6 +118,153 @@ describe("export-srt — karaoke word timings", () => {
   });
 });
 
+describe("export-srt — repeated karaoke phrase collapses per repetition", () => {
+  const t = tmpDir();
+  after(() => t.cleanup());
+
+  let project;
+  before(() => {
+    // The SAME phrase spoken twice back-to-back: caption --karaoke writes
+    // 2x2 adjacent same-text segments whose highlight ranges cycle. Each
+    // cycle must collapse into its own cue with the real word timings.
+    project = initDraft(t.dir, "chorus");
+    const words = [
+      ["0s", "0.5s", 0, 5], // hello (1st repetition)
+      ["0.5s", "0.5s", 6, 11], // world
+      ["1s", "0.5s", 0, 5], // hello (2nd repetition)
+      ["1.5s", "0.5s", 6, 11], // world
+    ];
+    for (const [start, duration, from, to] of words) {
+      const id = addText(project, start, duration, "hello world");
+      const styles = JSON.stringify([{ start: from, end: to, font_color: "#FFD700", bold: true }]);
+      const r = spawnCli(["text-ranges", project, id, "--styles", styles]);
+      assert.equal(r.status, 0, `stderr: ${r.stderr}`);
+    }
+  });
+
+  it("word SRT emits 4 cues with the stored timings, not 8 interpolated ones", () => {
+    const r = spawnCli(["export-srt", project, "--granularity", "word"]);
+    assert.equal(r.status, 0, `stderr: ${r.stderr}`);
+    const cues = parseSrt(r.stdout);
+    assert.deepEqual(
+      cues.map((c) => c.text),
+      ["hello", "world", "hello", "world"],
+    );
+    assert.deepEqual(
+      cues.map((c) => [c.startUs, c.endUs]),
+      [
+        [0, 500_000],
+        [500_000, 1_000_000],
+        [1_000_000, 1_500_000],
+        [1_500_000, 2_000_000],
+      ],
+    );
+  });
+
+  it("word VTT emits one karaoke cue per repetition", () => {
+    const r = spawnCli(["export-srt", project, "--granularity", "word", "--format", "vtt"]);
+    assert.equal(r.status, 0, `stderr: ${r.stderr}`);
+    assert.match(r.stdout, /00:00:00\.000 --> 00:00:01\.000\nhello <00:00:00\.500>world/);
+    assert.match(r.stdout, /00:00:01\.000 --> 00:00:02\.000\nhello <00:00:01\.500>world/);
+  });
+
+  it("keeps a rejected karaoke segment as its own highlighted word (no full-phrase explosion)", () => {
+    // Segments stored out of start order fail run validation; each must
+    // still export as ONE word at its own time, never the whole phrase
+    // interpolated into a single word's timeslot.
+    const entries = [
+      { startUs: 1_000_000, endUs: 1_500_000, text: "hi yo", styleRanges: [[0, 4]] },
+      { startUs: 0, endUs: 500_000, text: "hi yo", styleRanges: [[6, 10]] },
+    ];
+    const cues = collapseKaraokeRuns(entries);
+    assert.equal(cues.length, 2);
+    assert.deepEqual(cues[0].words, [{ word: "hi", startUs: 1_000_000, endUs: 1_500_000 }]);
+    assert.deepEqual(cues[1].words, [{ word: "yo", startUs: 0, endUs: 500_000 }]);
+  });
+
+  it("still interpolates a lone caption that merely emphasizes one word", () => {
+    const entries = [{ startUs: 0, endUs: 1_000_000, text: "hi yo", styleRanges: [[0, 4]] }];
+    const cues = collapseKaraokeRuns(entries);
+    assert.equal(cues.length, 1);
+    assert.equal(cues[0].words, undefined);
+  });
+});
+
+describe("srtTime/vttTime — millisecond rollover carries into seconds", () => {
+  it("carries a rounded-up millisecond field instead of emitting ,1000", () => {
+    assert.equal(srtTime(1_999_999), "00:00:02,000");
+    assert.equal(vttTime(1_999_999), "00:00:02.000");
+  });
+
+  it("carries across minute and hour boundaries", () => {
+    assert.equal(vttTime(3_599_999_600), "01:00:00.000");
+    assert.equal(srtTime(59_999_700), "00:01:00,000");
+  });
+
+  it("leaves non-rollover timestamps unchanged", () => {
+    assert.equal(srtTime(1_234_567), "00:00:01,235");
+    assert.equal(vttTime(1_400_000), "00:00:01.400");
+  });
+
+  it("export-srt --format vtt emits a spec-valid 3-digit fraction for rollover ends", () => {
+    const t = tmpDir();
+    try {
+      const project = initDraft(t.dir, "rollover");
+      addText(project, "0s", "1.999999s", "hello world");
+      const r = spawnCli(["export-srt", project, "--format", "vtt"]);
+      assert.equal(r.status, 0, `stderr: ${r.stderr}`);
+      assert.match(r.stdout, /00:00:00\.000 --> 00:00:02\.000\nhello world/);
+      assert.doesNotMatch(r.stdout, /\.\d{4}/);
+    } finally {
+      t.cleanup();
+    }
+  });
+});
+
+describe("renderVtt — inline timestamps and cue-text escaping", () => {
+  it("skips inline timestamps equal to the cue start or a previous timestamp", () => {
+    // Whisper can emit coincident word starts; a duplicate timestamp is
+    // invalid per the WebVTT spec, so the word joins the previous group.
+    const entries = [
+      { startUs: 0, endUs: 400_000, text: "a b", styleRanges: [[0, 2]] },
+      { startUs: 0, endUs: 800_000, text: "a b", styleRanges: [[4, 6]] },
+    ];
+    const vtt = renderVtt(collapseKaraokeRuns(entries), true);
+    assert.match(vtt, /00:00:00\.000 --> 00:00:00\.800\na b\n/);
+    assert.doesNotMatch(vtt, /<00:00:00\.000>/);
+  });
+
+  it("keeps strictly later timestamps after a skipped duplicate", () => {
+    const entries = [
+      { startUs: 0, endUs: 300_000, text: "a b c", styleRanges: [[0, 2]] },
+      { startUs: 0, endUs: 600_000, text: "a b c", styleRanges: [[4, 6]] },
+      { startUs: 600_000, endUs: 900_000, text: "a b c", styleRanges: [[8, 10]] },
+    ];
+    const vtt = renderVtt(collapseKaraokeRuns(entries), true);
+    assert.match(vtt, /a b <00:00:00\.600>c/);
+  });
+
+  it("escapes & and < in VTT cue text so nothing is swallowed as a tag", () => {
+    const t = tmpDir();
+    try {
+      const project = initDraft(t.dir, "escape");
+      addText(project, "0s", "1s", "i <3 this & that");
+      const vtt = spawnCli(["export-srt", project, "--format", "vtt"]);
+      assert.equal(vtt.status, 0, `stderr: ${vtt.stderr}`);
+      assert.match(vtt.stdout, /i &lt;3 this &amp; that/);
+      const word = spawnCli(["export-srt", project, "--format", "vtt", "--granularity", "word"]);
+      assert.equal(word.status, 0, `stderr: ${word.stderr}`);
+      assert.match(word.stdout, /<00:00:0\d\.\d{3}>&lt;3/);
+      // SRT has no markup semantics: text stays raw.
+      const srt = spawnCli(["export-srt", project]);
+      assert.equal(srt.status, 0, `stderr: ${srt.stderr}`);
+      assert.match(srt.stdout, /i <3 this & that/);
+    } finally {
+      t.cleanup();
+    }
+  });
+});
+
 describe("export-srt — flag validation and empty drafts", () => {
   const t = tmpDir();
   after(() => t.cleanup());

From 7ac470c80673df9148d097f2ac82fa6c7db52ec7 Mon Sep 17 00:00:00 2001
From: Rene Zander <renezander030@gmail.com>
Date: Wed, 8 Jul 2026 10:38:06 +0000
Subject: [PATCH 12/17] fix(keyframe): easing validation, stale bezier handles,
 and lone-keyframe semantics

Fixes four confirmed v0.13.0 code-review findings:

- Easing validation bypassed by inherited prototype names: resolveEasing
  used 'easing in EASING_PROFILES', so Object.prototype members
  (hasOwnProperty, toString, constructor, ...) passed validation and
  applyEasing read undefined ratios, NaN-corrupting the draft with
  "x": null control points at exit 0. Now Object.hasOwn; same hardening
  applied to the PROPERTY_MAP lookups in parseKeyframeValue/addKeyframes.

- Linear keyframe insert between an eased pair left stale out-of-range
  bezier handles: the neighbours' facing handles were computed against
  the old prev->next interval and could reach past the inserted keyframe
  (overshoot + snap-back in CapCut). A linear insert now clears both
  neighbours' facing handles and drops a neighbour back to curveType
  Line when it is left with no handles at all; far-side eased segments
  are untouched.

- compile --check accepted an invalid keyframe easing and the real
  compile failed only after initDraft had seeded the draft directory,
  leaving an orphan half-built draft. validateSpec now pre-flights the
  easing field with the same resolveEasing check the write path uses, so
  --check rejects it and compile fails before anything is written.

- Single-keyframe --easing silently stamped curveType FreeCurveInOut
  with zero-length handles. A lone eased keyframe now stays Line, exits
  0 with a warning on stderr (and a warnings field in the JSON output),
  and picks up the curve when its pair keyframe is added with an easing;
  compile surfaces the same warning in its warnings array. Help text and
  the keyframe --easing option description updated accordingly.
---
 src/command-specs.ts          |  14 ++--
 src/compile.ts                |  32 ++++++---
 src/decorators.ts             |  82 +++++++++++++++++----
 src/index.ts                  |  19 ++++-
 test/compile.test.mjs         |  54 +++++++++++++-
 test/keyframe-easing.test.mjs | 132 ++++++++++++++++++++++++++++++++++
 6 files changed, 303 insertions(+), 30 deletions(-)

diff --git a/src/command-specs.ts b/src/command-specs.ts
index 26ae987..7c04cb6 100644
--- a/src/command-specs.ts
+++ b/src/command-specs.ts
@@ -233,10 +233,16 @@ const optionsByCommand: Record<string, OptionSpec[]> = {
   cut: [OUT],
   keyframe: [
     option("batch", ["--batch"], "boolean", "Read JSONL keyframes from stdin."),
-    option("easing", ["--easing"], "enum", "Interpolation easing to adjacent keyframes.", {
-      values: ["linear", "ease-in", "ease-out", "ease-in-out"],
-      default: "linear",
-    }),
+    option(
+      "easing",
+      ["--easing"],
+      "enum",
+      "Interpolation easing to adjacent keyframes. Needs an adjacent keyframe on the same property; a lone eased keyframe stays linear (warns).",
+      {
+        values: ["linear", "ease-in", "ease-out", "ease-in-out"],
+        default: "linear",
+      },
+    ),
   ],
   transition: [option("duration", ["--duration"], "time", "Transition duration.")],
   mask: [
diff --git a/src/compile.ts b/src/compile.ts
index 6dadcaa..b7dccb4 100644
--- a/src/compile.ts
+++ b/src/compile.ts
@@ -3,6 +3,7 @@ import { basename, dirname, isAbsolute, resolve } from "node:path";
 import {
   addKeyframes,
   addTransition,
+  resolveEasing,
   setTextRanges,
   setTextStyle,
   type TextRangeInput,
@@ -252,6 +253,19 @@ function validateSpec(spec: unknown): asserts spec is CompileSpec {
         throw new Error(`compile: operations[${index}].target must reference a declared item ref`);
       }
     }
+    // Pre-flight the keyframe easing with the exact validation the real write
+    // performs, so --check rejects what compile would reject and a bad easing
+    // never fails AFTER initDraft seeded the draft directory (orphan dir).
+    if (op.op === "keyframe" && op.easing !== undefined) {
+      if (typeof op.easing !== "string") {
+        throw new Error(`compile: operations[${index}].easing must be a string`);
+      }
+      try {
+        resolveEasing(op.easing);
+      } catch (e) {
+        throw new Error(`compile: operations[${index}]: ${(e as Error).message}`);
+      }
+    }
   }
 }
 
@@ -438,14 +452,16 @@ export function compileDraft(spec: CompileSpec, opts: CompileOptions): CompileRe
         segments++;
         break;
       case "keyframe":
-        addKeyframes(draft, resolveRef(operation.target), [
-          {
-            property: operation.property,
-            timeUs: Math.round(operation.time * US),
-            value: operation.value,
-            easing: operation.easing,
-          },
-        ]);
+        warnings.push(
+          ...addKeyframes(draft, resolveRef(operation.target), [
+            {
+              property: operation.property,
+              timeUs: Math.round(operation.time * US),
+              value: operation.value,
+              easing: operation.easing,
+            },
+          ]).warnings,
+        );
         break;
       case "audio-fade":
         setAudioFade(draft, resolveRef(operation.target), {
diff --git a/src/decorators.ts b/src/decorators.ts
index 5106278..3a4b057 100644
--- a/src/decorators.ts
+++ b/src/decorators.ts
@@ -53,16 +53,21 @@ export function keyframeEasings(): string[] {
   return ["linear", ...Object.keys(EASING_PROFILES)];
 }
 
-function resolveEasing(easing: string | undefined): EasingName {
+// Exported so compile's spec validation pre-flights the exact same check
+// (and error message) the real keyframe write performs. Object.hasOwn, not
+// `in`: inherited Object.prototype names ("hasOwnProperty", "toString",
+// "constructor", ...) must NOT pass — EASING_PROFILES[name] would resolve to
+// an inherited function whose ratios are undefined and NaN-corrupt the draft.
+export function resolveEasing(easing: string | undefined): EasingName {
   if (easing === undefined) return "linear";
-  if (easing !== "linear" && !(easing in EASING_PROFILES)) {
+  if (easing !== "linear" && !Object.hasOwn(EASING_PROFILES, easing)) {
     throw new Error(`Unsupported keyframe easing: ${easing}. Supported: ${keyframeEasings().join(", ")}`);
   }
   return easing as EasingName;
 }
 
 export function parseKeyframeValue(property: string, value: string): number {
-  if (!(property in PROPERTY_MAP)) {
+  if (!Object.hasOwn(PROPERTY_MAP, property)) {
     throw new Error(`Unsupported keyframe property: ${property}. Supported: ${Object.keys(PROPERTY_MAP).join(", ")}`);
   }
   const v = value.trim();
@@ -141,22 +146,58 @@ interface KeyframeListObject {
   property_type: string;
 }
 
+// Nearest existing keyframes strictly before/after the given time — the two
+// segment neighbours whose facing handles an insert at that time affects.
+function findNeighbours(
+  list: KeyframeEntry[],
+  timeOffset: number,
+): { prev: KeyframeEntry | undefined; next: KeyframeEntry | undefined } {
+  let prev: KeyframeEntry | undefined;
+  let next: KeyframeEntry | undefined;
+  for (const k of list) {
+    if (k.time_offset < timeOffset && (!prev || k.time_offset > prev.time_offset)) prev = k;
+    if (k.time_offset > timeOffset && (!next || k.time_offset < next.time_offset)) next = k;
+  }
+  return { prev, next };
+}
+
+const isZeroControl = (c: ControlPoint): boolean => c.x === 0 && c.y === 0;
+
+// Inserting a LINEAR keyframe between two keyframes invalidates the handles
+// that faced across the old prev→next segment: prev's outgoing and next's
+// incoming handles were computed against an interval/Δ that no longer exists,
+// so left as-is they can point past the inserted keyframe (overshoot + snap
+// back in CapCut). Clear the facing handles — the inserted keyframe's easing
+// wins, mirroring applyEasing — and drop a neighbour back to "Line" when it is
+// left with no handles at all, so curveType never contradicts the handles.
+function clearFacingHandles(list: KeyframeEntry[], timeOffset: number): void {
+  const { prev, next } = findNeighbours(list, timeOffset);
+  if (prev) {
+    prev.right_control = { x: 0, y: 0 };
+    if (isZeroControl(prev.left_control)) prev.curveType = "Line";
+  }
+  if (next) {
+    next.left_control = { x: 0, y: 0 };
+    if (isZeroControl(next.right_control)) next.curveType = "Line";
+  }
+}
+
 // Stamp the inserted keyframe and retro-update the facing handles of its two
 // neighbours so the easing applies to both adjacent segments — the easing of
 // the inserted keyframe wins, matching CapCut UI behaviour when a preset is
-// applied to a keyframe.
-function applyEasing(list: KeyframeEntry[], entry: KeyframeEntry, easing: Exclude<EasingName, "linear">): void {
+// applied to a keyframe. Returns false (leaving the entry as "Line") when the
+// list has no neighbour to ease against: a lone keyframe encodes no curve, and
+// stamping FreeCurveInOut with zero-length handles would write a curve-type
+// marker its handles contradict. The stamp happens later instead, when the
+// pair's second keyframe is inserted with an easing and retro-updates this one.
+function applyEasing(list: KeyframeEntry[], entry: KeyframeEntry, easing: Exclude<EasingName, "linear">): boolean {
   const profile = EASING_PROFILES[easing];
   const rightY = (fromValue: number, toValue: number): number =>
     easing === "ease-out" ? Math.round(EASE_OUT_RIGHT_Y_RATIO * (toValue - fromValue) * 1e6) / 1e6 : 0;
 
+  const { prev, next } = findNeighbours(list, entry.time_offset);
+  if (!prev && !next) return false;
   entry.curveType = "FreeCurveInOut";
-  let prev: KeyframeEntry | undefined;
-  let next: KeyframeEntry | undefined;
-  for (const k of list) {
-    if (k.time_offset < entry.time_offset && (!prev || k.time_offset > prev.time_offset)) prev = k;
-    if (k.time_offset > entry.time_offset && (!next || k.time_offset < next.time_offset)) next = k;
-  }
   if (prev) {
     const interval = entry.time_offset - prev.time_offset;
     prev.curveType = "FreeCurveInOut";
@@ -175,6 +216,7 @@ function applyEasing(list: KeyframeEntry[], entry: KeyframeEntry, easing: Exclud
       y: rightY(entry.values[0], next.values[0]),
     };
   }
+  return true;
 }
 
 export function addKeyframes(
@@ -182,7 +224,7 @@ export function addKeyframes(
   segmentId: string,
   keyframes: KeyframeInput[],
   easing?: string,
-): { segmentId: string; added: number; lists: Array<{ property: string; count: number }> } {
+): { segmentId: string; added: number; lists: Array<{ property: string; count: number }>; warnings: string[] } {
   resolveEasing(easing); // fail fast even when every keyframe overrides it
   const found = findSegment(draft, segmentId);
   if (!found) throw new Error(`Segment not found: ${segmentId}`);
@@ -192,9 +234,10 @@ export function addKeyframes(
     (seg as Record<string, unknown>).common_keyframes = [];
   }
   const commonKeyframes = seg.common_keyframes as KeyframeListObject[];
+  const warnings: string[] = [];
 
   for (const kf of keyframes) {
-    const propEnum = PROPERTY_MAP[kf.property];
+    const propEnum = Object.hasOwn(PROPERTY_MAP, kf.property) ? PROPERTY_MAP[kf.property] : undefined;
     if (!propEnum) {
       throw new Error(
         `Unsupported keyframe property: ${kf.property}. Supported: ${Object.keys(PROPERTY_MAP).join(", ")}`,
@@ -220,7 +263,16 @@ export function addKeyframes(
       time_offset: kf.timeUs,
       values: [kf.value],
     };
-    if (kfEasing !== "linear") applyEasing(list.keyframe_list, entry, kfEasing);
+    if (kfEasing !== "linear") {
+      if (!applyEasing(list.keyframe_list, entry, kfEasing)) {
+        warnings.push(
+          `easing '${kfEasing}' for ${kf.property} at ${kf.timeUs}us has no adjacent keyframe to ease against; ` +
+            `wrote a linear keyframe — it picks up the curve when its pair keyframe is added with an easing`,
+        );
+      }
+    } else {
+      clearFacingHandles(list.keyframe_list, entry.time_offset);
+    }
     list.keyframe_list.push(entry);
     list.keyframe_list.sort((a, b) => a.time_offset - b.time_offset);
   }
@@ -230,7 +282,7 @@ export function addKeyframes(
     return { property: prop, count: l.keyframe_list.length };
   });
 
-  return { segmentId: seg.id, added: keyframes.length, lists: summary };
+  return { segmentId: seg.id, added: keyframes.length, lists: summary, warnings };
 }
 
 // --- Phase 1: transition / mask / bg-blur / text-style / text-anim ---
diff --git a/src/index.ts b/src/index.ts
index 4ca520f..8940cc3 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -336,7 +336,12 @@ Animate:
              Values: "1.5", "50%" (alpha/volume), "45deg" (rotation),
                      "+0.5"/"-0.3" (saturation/contrast/brightness)
              Easing: linear (default), ease-in, ease-out, ease-in-out — written
-                     as CapCut bezier handles (ease-out = the UI's "Cubic Out")
+                     as CapCut bezier handles (ease-out = the UI's "Cubic Out").
+                     Easing needs an adjacent keyframe on the same property: a
+                     lone eased keyframe stays linear (warns) and picks up the
+                     curve when its pair is added with an easing. A linear
+                     insert between eased keyframes resets the neighbours'
+                     facing handles, so both new sub-segments render linear.
 
   transition <project> <id> <slug> [--duration <s>]
              Attach a transition to a video/image segment. Slug examples:
@@ -1656,7 +1661,17 @@ function cmdKeyframe(draft: Draft, filePath: string, positional: string[], flags
 
   const result = addKeyframes(draft, segId, inputs, flags.easing);
   saveDraft(filePath, draft);
-  out({ ok: true, id: result.segmentId, added: result.added, lists: result.lists }, flags);
+  for (const warning of result.warnings) process.stderr.write(`Warning: ${warning}\n`);
+  out(
+    {
+      ok: true,
+      id: result.segmentId,
+      added: result.added,
+      lists: result.lists,
+      ...(result.warnings.length ? { warnings: result.warnings } : {}),
+    },
+    flags,
+  );
 }
 
 function cmdTransition(draft: Draft, filePath: string, positional: string[], flags: Flags): void {
diff --git a/test/compile.test.mjs b/test/compile.test.mjs
index b9fd573..88bf27a 100644
--- a/test/compile.test.mjs
+++ b/test/compile.test.mjs
@@ -1,5 +1,5 @@
 import assert from "node:assert/strict";
-import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { after, describe, it } from "node:test";
@@ -178,3 +178,55 @@ describe("compile", () => {
     assert.match(r.stderr, /not valid JSON/);
   });
 });
+
+// v0.13.0 review: validateSpec never checked the keyframe `easing` field, so
+// `compile --check` exited 0 on a spec the real compile would reject — and the
+// real compile only threw AFTER initDraft had seeded the draft directory,
+// leaving an orphan half-built draft that CapCut lists.
+describe("compile: keyframe easing pre-flight", () => {
+  const specWithEasing = (easing) => ({
+    name: "K",
+    tracks: [{ type: "video", items: [{ path: "clip1.mp4", start: 0, duration: 2, ref: "v1" }] }],
+    operations: [{ op: "keyframe", target: "v1", property: "uniform_scale", time: 1, value: 1.2, easing }],
+  });
+
+  it("--check rejects an invalid easing instead of green-lighting it", () => {
+    const s = setup();
+    after(s.cleanup);
+    const spec = writeSpec(s.dir, specWithEasing("cubic-out"));
+    const r = spawnCli(["compile", spec, "--check"]);
+    assert.equal(r.status, 1);
+    assert.match(r.stderr, /Unsupported keyframe easing: cubic-out/);
+  });
+
+  it("real compile fails before initDraft writes anything (no orphan draft dir)", () => {
+    const s = setup();
+    after(s.cleanup);
+    const spec = writeSpec(s.dir, specWithEasing("cubic-out"));
+    const out = join(s.dir, "outdraft");
+    const r = spawnCli(["compile", spec, "--out", out]);
+    assert.equal(r.status, 1);
+    assert.match(r.stderr, /Unsupported keyframe easing: cubic-out/);
+    assert.equal(existsSync(out), false, "orphan half-built draft dir left behind");
+  });
+
+  it("rejects inherited prototype names in specs too", () => {
+    const s = setup();
+    after(s.cleanup);
+    const spec = writeSpec(s.dir, specWithEasing("hasOwnProperty"));
+    const r = spawnCli(["compile", spec, "--check"]);
+    assert.equal(r.status, 1);
+    assert.match(r.stderr, /Unsupported keyframe easing: hasOwnProperty/);
+  });
+
+  it("--check and compile both accept every supported easing", () => {
+    const s = setup();
+    after(s.cleanup);
+    const spec = writeSpec(s.dir, specWithEasing("ease-out"));
+    assert.equal(spawnCli(["compile", spec, "--check"]).status, 0);
+    const out = join(s.dir, "Built");
+    const r = spawnCli(["compile", spec, "--out", out]);
+    assert.equal(r.status, 0, r.stderr);
+    assert.equal(r.json.ok, true);
+  });
+});
diff --git a/test/keyframe-easing.test.mjs b/test/keyframe-easing.test.mjs
index 0ca9d7b..41bc8cf 100644
--- a/test/keyframe-easing.test.mjs
+++ b/test/keyframe-easing.test.mjs
@@ -169,6 +169,138 @@ describe("keyframe --easing: rejection", () => {
   });
 });
 
+// v0.13.0 review: `easing in EASING_PROFILES` matched inherited
+// Object.prototype members, so EASING_PROFILES[easing] resolved to an
+// inherited function whose ratios are undefined — Math.round(undefined ×
+// interval) = NaN, serialized by JSON.stringify as `"x": null` control
+// points, with exit 0. Every prototype name must be rejected up front.
+describe("keyframe --easing: inherited prototype names are rejected", () => {
+  const fix = tmpDraft();
+  after(() => fix.cleanup());
+
+  for (const name of ["hasOwnProperty", "toString", "constructor", "valueOf", "__proto__", "isPrototypeOf"]) {
+    it(`rejects '${name}' on the flag`, () => {
+      const r = spawnCli(["keyframe", fix.path, SEG, "uniform_scale", "3s", "1.3", "--easing", name]);
+      assert.equal(r.status, 1);
+      assert.match(r.stderr, new RegExp(`Unsupported keyframe easing: ${name}`));
+    });
+  }
+
+  it("rejects a prototype name on a batch line and leaves the draft uncorrupted", () => {
+    // Mirrors the reviewer's reproduction: two keyframes with easing
+    // "toString" used to exit 0 and write "x": null into draft_content.json.
+    const lines = [
+      JSON.stringify({ property: "uniform_scale", time: 0, value: "1.0", easing: "toString" }),
+      JSON.stringify({ property: "uniform_scale", time: 3000000, value: "1.3", easing: "toString" }),
+    ].join("\n");
+    const r = spawnCli(["keyframe", fix.path, SEG, "--batch"], { input: lines });
+    assert.equal(r.status, 1);
+    assert.match(r.stderr, /Unsupported keyframe easing: toString/);
+    const raw = readFileSync(fix.path, "utf-8");
+    assert.ok(!/"x":\s*null/.test(raw), "draft contains null control points");
+    assert.equal(keyframeList(fix.path, "UNIFORM_SCALE").length, 0);
+  });
+
+  it("rejects inherited prototype names as keyframe properties too", () => {
+    const r = spawnCli(["keyframe", fix.path, SEG, "toString", "0s", "1.0"]);
+    assert.equal(r.status, 1);
+    assert.match(r.stderr, /Unsupported keyframe property: toString/);
+  });
+});
+
+// v0.13.0 review: a plain (linear) insert skipped the neighbour handle
+// updates entirely, so an eased pair kept facing handles computed against the
+// OLD prev→next interval — t=0's right handle reached 1.6s into a segment now
+// only 1s long (overshoot toward ~1.47 + snap-back in CapCut).
+describe("keyframe: linear insert between an eased pair clears stale handles", () => {
+  it("resets both neighbours' facing handles (and curveType when bare)", () => {
+    const fix = tmpDraft();
+    after(() => fix.cleanup());
+    assert.equal(spawnCli(["keyframe", fix.path, SEG, "uniform_scale", "0s", "1.0"]).status, 0);
+    assert.equal(spawnCli(["keyframe", fix.path, SEG, "uniform_scale", "5s", "1.5", "--easing", "ease-out"]).status, 0);
+    // Sanity: the eased pair carries the reviewer-observed handle first.
+    let list = keyframeList(fix.path, "UNIFORM_SCALE");
+    assert.deepEqual(list[0].right_control, { x: 1600000, y: 0.47 });
+
+    // v0.12-style plain insert between the pair.
+    assert.equal(spawnCli(["keyframe", fix.path, SEG, "uniform_scale", "1s", "1.1"]).status, 0);
+    list = keyframeList(fix.path, "UNIFORM_SCALE");
+    assert.equal(list.length, 3);
+    // No handle may point at a keyframe that is no longer the segment
+    // neighbour: both split sub-segments render linear.
+    assert.deepEqual(
+      list.map((k) => ({ t: k.time_offset, curve: k.curveType, left: k.left_control, right: k.right_control })),
+      [
+        { t: 0, curve: "Line", left: { x: 0, y: 0 }, right: { x: 0, y: 0 } },
+        { t: 1000000, curve: "Line", left: { x: 0, y: 0 }, right: { x: 0, y: 0 } },
+        { t: 5000000, curve: "Line", left: { x: 0, y: 0 }, right: { x: 0, y: 0 } },
+      ],
+    );
+  });
+
+  it("keeps easing on segments the insert does not split", () => {
+    const fix = tmpDraft();
+    after(() => fix.cleanup());
+    // Oracle triplet at 0 / 5s / 8.133333s ease-out, then a linear insert at
+    // 6s: only the 5s→8.13s segment is split; the 0→5s easing must survive.
+    for (const { time, value } of [
+      { time: 0, value: "1.0" },
+      { time: 5000000, value: "1.3" },
+      { time: 8133333, value: "1.0" },
+    ]) {
+      const line = JSON.stringify({ property: "scale_x", time, value, easing: "ease-out" });
+      assert.equal(spawnCli(["keyframe", fix.path, SEG, "--batch"], { input: line }).status, 0);
+    }
+    assert.equal(spawnCli(["keyframe", fix.path, SEG, "scale_x", "6s", "1.1"]).status, 0);
+    const list = keyframeList(fix.path, "KFTypeScaleX");
+    assert.equal(list.length, 4);
+    // 0→5s eased segment untouched.
+    assert.equal(list[0].curveType, "FreeCurveInOut");
+    assert.deepEqual(list[0].right_control, { x: 1600000, y: 0.282 });
+    assert.deepEqual(list[1].left_control, { x: -2000000, y: 0 });
+    // 5s keyframe keeps its incoming handle but loses the stale outgoing one.
+    assert.equal(list[1].curveType, "FreeCurveInOut");
+    assert.deepEqual(list[1].right_control, { x: 0, y: 0 });
+    // Inserted keyframe and the old segment end are fully linear now.
+    assert.equal(list[2].curveType, "Line");
+    assert.equal(list[3].curveType, "Line");
+    assert.deepEqual(list[3].left_control, { x: 0, y: 0 });
+  });
+});
+
+// v0.13.0 review: a lone --easing keyframe used to stamp curveType
+// FreeCurveInOut with zero-length handles — a curve marker its handles
+// contradict, and no signal that the requested easing encoded nothing.
+describe("keyframe --easing: lone keyframe has no neighbour to ease against", () => {
+  const fix = tmpDraft();
+  after(() => fix.cleanup());
+
+  it("stays Line, exits 0, and warns on stderr", () => {
+    const r = spawnCli(["keyframe", fix.path, SEG, "alpha", "2s", "0.5", "--easing", "ease-out"]);
+    assert.equal(r.status, 0, `stderr: ${r.stderr}`);
+    assert.match(r.stderr, /no adjacent keyframe to ease against/);
+    assert.equal(r.json.warnings.length, 1);
+    const list = keyframeList(fix.path, "KFTypeAlpha");
+    assert.equal(list.length, 1);
+    assert.equal(list[0].curveType, "Line");
+    assert.deepEqual(list[0].left_control, { x: 0, y: 0 });
+    assert.deepEqual(list[0].right_control, { x: 0, y: 0 });
+  });
+
+  it("picks up the curve when the pair keyframe arrives with an easing", () => {
+    const r = spawnCli(["keyframe", fix.path, SEG, "alpha", "5s", "1.0", "--easing", "ease-out"]);
+    assert.equal(r.status, 0, `stderr: ${r.stderr}`);
+    assert.equal(r.json.warnings, undefined);
+    const list = keyframeList(fix.path, "KFTypeAlpha");
+    assert.equal(list.length, 2);
+    // 0.32 × 3s interval; y = round(0.94 × (1.0 − 0.5), 6).
+    assert.equal(list[0].curveType, "FreeCurveInOut");
+    assert.deepEqual(list[0].right_control, { x: 960000, y: 0.47 });
+    assert.equal(list[1].curveType, "FreeCurveInOut");
+    assert.deepEqual(list[1].left_control, { x: -1200000, y: 0 });
+  });
+});
+
 describe("ken-burns.sh easing default", () => {
   function runKenBurns(fix, extra = []) {
     return spawnSync("bash", [KEN_BURNS, fix.path, SEG, "1.0", "1.2", "0", "-0.1", "0", "-0.05", "3s", ...extra], {

From 4a54f8d623bde25fd0c97b825614c898ea97f20c Mon Sep 17 00:00:00 2001
From: Rene Zander <renezander030@gmail.com>
Date: Wed, 8 Jul 2026 10:45:13 +0000
Subject: [PATCH 13/17] fix(scenes): video-stream duration, honest spawn
 errors, timecode carry

- detect-scenes: derive the final segment end from the VIDEO stream's
  duration via ffprobe (probeMedia) instead of the container Duration
  header (the longest stream). With an audio track outlasting the video,
  segments no longer point past the last video frame. Falls back to the
  container duration only when ffprobe is unavailable; new
  duration_source field ("video-stream" | "container") and human output
  note say which was used. New --ffprobe-cmd option (matches
  add-video/compile); cuts past the known end are now dropped from
  cuts[] too, so cuts[] and segments[] agree.
- detect-scenes: distinguish spawnSync failure modes. ETIMEDOUT now
  reports "scene detection timed out after Ns" and ENOBUFS reports
  "output exceeded the N MiB buffer" instead of falsely claiming
  "ffmpeg is unavailable - install ffmpeg" when ffmpeg actually ran.
  Timeout/buffer caps exposed as SceneDetectOptions (defaults
  unchanged: 600s / 64 MiB).
- timecode(): round to whole milliseconds first so round-up carries
  through seconds/minutes/hours; 59.9996 now formats as "00:01:00.000"
  instead of the out-of-range "00:00:60.000".
- probe: parseMediaProbe/MediaProbe expose videoDurationUs (the video
  stream's own duration) alongside the container durationUs.

Findings addressed:
1. Final segment end uses container Duration (longest stream), so
   segments extend past the end of the video track (src/scenes.ts).
2. ffmpeg timeout (600s) or maxBuffer overflow is misreported as
   "ffmpeg is unavailable - install ffmpeg" (src/scenes.ts).
3. timecode() emits invalid timestamps like "00:00:60.000" when
   milliseconds round up to a full minute (src/scenes.ts).
---
 src/command-specs.ts        |   8 ++-
 src/index.ts                |  19 +++++-
 src/probe.ts                |   5 +-
 src/scenes.ts               |  71 +++++++++++++++++---
 test/detect-scenes.test.mjs | 127 +++++++++++++++++++++++++++++++++++-
 test/probe.test.mjs         |  16 +++++
 6 files changed, 233 insertions(+), 13 deletions(-)

diff --git a/src/command-specs.ts b/src/command-specs.ts
index 26ae987..5848963 100644
--- a/src/command-specs.ts
+++ b/src/command-specs.ts
@@ -418,6 +418,12 @@ const optionsByCommand: Record<string, OptionSpec[]> = {
     }),
     option("limit", ["--limit"], "number", "Keep only the N strongest cuts."),
     option("ffmpeg_cmd", ["--ffmpeg-cmd"], "path", "FFmpeg binary."),
+    option(
+      "ffprobe_cmd",
+      ["--ffprobe-cmd"],
+      "path",
+      "ffprobe binary for the video-stream duration (falls back to the container duration without it).",
+    ),
     option("json", ["--json"], "boolean", "Force JSON output (the default; overrides -H)."),
   ],
 };
@@ -510,7 +516,7 @@ export function buildCommandSpecs(commands: readonly string[], summaries: Record
     const usage = usages[name as CommandName] ?? `capcut ${name} <project>`;
     const prerequisites: string[] = [];
     if (name === "render" || name === "detect-scenes") prerequisites.push("ffmpeg");
-    if (["add-video", "add-audio", "compile"].includes(name)) prerequisites.push("ffprobe (optional)");
+    if (["add-video", "add-audio", "compile", "detect-scenes"].includes(name)) prerequisites.push("ffprobe (optional)");
     if (name === "caption") prerequisites.push("whisper CLI");
     if (name === "translate") prerequisites.push("ANTHROPIC_API_KEY or --api-key");
     if (["add-video", "add-audio"].includes(name)) prerequisites.push("network for Wikimedia URLs only");
diff --git a/src/index.ts b/src/index.ts
index 4ca520f..ed75049 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -250,12 +250,18 @@ Analyze:
              in seconds AND microseconds (the draft-native unit), ready to
              seed a long-form-to-shorts split: feed the segments into
              "capcut compile" (one clip per segment) or "capcut cut".
-             Detection only — it never touches a draft. Options:
+             The final segment ends at the VIDEO stream's real duration
+             (read via ffprobe), so it never overruns the video when a
+             longer audio track pads the container; without ffprobe it
+             falls back to the container duration and duration_source
+             says so. Detection only — it never touches a draft. Options:
                --threshold <n>    Scene score a cut must exceed, 0..1 (default 0.4)
                --min-gap <s>      Merge cuts closer than <s> seconds, keeping
                                   the strongest (default 2)
                --limit <n>        Keep only the <n> strongest cuts
                --ffmpeg-cmd <p>   ffmpeg binary (default ffmpeg)
+               --ffprobe-cmd <p>  ffprobe binary for the video-stream
+                                  duration (default ffprobe)
                --json             Force JSON output (the default; overrides -H)
 
 Add:
@@ -3255,11 +3261,20 @@ function cmdDetectScenes(positional: string[], flags: Flags): void {
     minGap,
     limit: flags.limit,
     ffmpegCmd: flags.ffmpegCmd,
+    ffprobeCmd: flags.ffprobeCmd,
   });
   // --json forces machine output even when a config/alias turned on --human.
   if (flags.human && !flags.json) {
     console.log(`Video:     ${report.video}`);
-    console.log(`Duration:  ${report.duration === null ? "unknown" : formatDuration(report.duration_us ?? 0)}`);
+    const durationNote =
+      report.duration_source === "video-stream"
+        ? " (video stream)"
+        : report.duration_source === "container"
+          ? " (container header — ffprobe unavailable; may include audio past the video track)"
+          : "";
+    console.log(
+      `Duration:  ${report.duration === null ? "unknown" : formatDuration(report.duration_us ?? 0)}${durationNote}`,
+    );
     console.log(
       `Threshold: ${report.threshold}  (min gap ${report.min_gap}s${report.limit ? `, limit ${report.limit}` : ""})`,
     );
diff --git a/src/probe.ts b/src/probe.ts
index 5451193..a0b9247 100644
--- a/src/probe.ts
+++ b/src/probe.ts
@@ -29,7 +29,8 @@ export interface MediaProbe {
   width: number | null;
   height: number | null;
   rotation: number;
-  durationUs: number | null;
+  durationUs: number | null; // container duration (the LONGEST stream)
+  videoDurationUs: number | null; // the video stream's own duration, when the container reports it
   fps: number | null;
   hasVideo: boolean;
   hasAudio: boolean;
@@ -76,11 +77,13 @@ export function parseMediaProbe(json: string): MediaProbe | null {
 
   const format = (parsed.format ?? {}) as Record<string, unknown>;
   const durationSeconds = fraction(format.duration) ?? fraction(video?.duration) ?? fraction(audio?.duration);
+  const videoDurationSeconds = fraction(video?.duration);
   return {
     width,
     height,
     rotation,
     durationUs: durationSeconds === null ? null : Math.round(durationSeconds * 1_000_000),
+    videoDurationUs: videoDurationSeconds === null ? null : Math.round(videoDurationSeconds * 1_000_000),
     fps: fraction(video?.avg_frame_rate) ?? fraction(video?.r_frame_rate),
     hasVideo: Boolean(video),
     hasAudio: Boolean(audio),
diff --git a/src/scenes.ts b/src/scenes.ts
index 63ea019..f50f99c 100644
--- a/src/scenes.ts
+++ b/src/scenes.ts
@@ -1,5 +1,6 @@
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
+import { probeMedia } from "./probe.js";
 
 /**
  * Deterministic scene-cut detection (ffmpeg scene filter, no AI).
@@ -39,6 +40,9 @@ export interface SceneDetectOptions {
   minGap?: number; // merge cuts closer than this many seconds (default 2)
   limit?: number; // keep only the N strongest cuts
   ffmpegCmd?: string; // ffmpeg binary (default "ffmpeg")
+  ffprobeCmd?: string; // ffprobe binary for video-stream duration (default "ffprobe")
+  timeoutMs?: number; // kill ffmpeg after this long (default 600s)
+  maxBufferBytes?: number; // ffmpeg stdout/stderr cap (default 64 MiB)
 }
 
 export interface SceneReport {
@@ -48,6 +52,10 @@ export interface SceneReport {
   limit: number | null;
   duration: number | null;
   duration_us: number | null;
+  // Where `duration` came from: the video stream itself (ffprobe — the value
+  // segments must end at), or the container header (the LONGEST stream; only
+  // used when ffprobe is unavailable, may overrun the video track).
+  duration_source: "video-stream" | "container" | null;
   cuts: Array<{ time: number; time_us: number; timecode: string; score: number }>;
   segments: SceneSegment[];
 }
@@ -136,11 +144,16 @@ export function buildSceneSegments(cuts: SceneCut[], duration: number | null): S
   });
 }
 
-/** Format seconds as hh:mm:ss.mmm. */
+/**
+ * Format seconds as hh:mm:ss.mmm. Rounds to milliseconds FIRST so the carry
+ * propagates through seconds/minutes/hours — 59.9996 must become
+ * "00:01:00.000", never the out-of-range "00:00:60.000".
+ */
 export function timecode(seconds: number): string {
-  const h = Math.floor(seconds / 3600);
-  const m = Math.floor((seconds % 3600) / 60);
-  const s = seconds % 60;
+  const totalMs = Math.round(seconds * 1000);
+  const h = Math.floor(totalMs / 3_600_000);
+  const m = Math.floor((totalMs % 3_600_000) / 60_000);
+  const s = (totalMs % 60_000) / 1000;
   const pad = (n: number) => n.toString().padStart(2, "0");
   return `${pad(h)}:${pad(m)}:${s.toFixed(3).padStart(6, "0")}`;
 }
@@ -158,6 +171,8 @@ export function detectScenes(videoPath: string, opts: SceneDetectOptions = {}):
   const threshold = opts.threshold ?? 0.4;
   const minGap = opts.minGap ?? 2;
   const cmd = opts.ffmpegCmd ?? "ffmpeg";
+  const timeoutMs = opts.timeoutMs ?? 600_000;
+  const maxBuffer = opts.maxBufferBytes ?? 64 * 1024 * 1024;
   if (!existsSync(videoPath)) {
     throw new Error(`detect-scenes: video not found: ${videoPath}`);
   }
@@ -174,7 +189,7 @@ export function detectScenes(videoPath: string, opts: SceneDetectOptions = {}):
   ];
   let r: ReturnType<typeof spawnSync>;
   try {
-    r = spawnSync(cmd, args, { encoding: "utf-8", timeout: 600_000, maxBuffer: 64 * 1024 * 1024 });
+    r = spawnSync(cmd, args, { encoding: "utf-8", timeout: timeoutMs, maxBuffer });
   } catch (e) {
     throw new Error(
       `detect-scenes: ffmpeg is unavailable at '${cmd}'. Install ffmpeg or pass --ffmpeg-cmd <path>. (${
@@ -183,14 +198,53 @@ export function detectScenes(videoPath: string, opts: SceneDetectOptions = {}):
     );
   }
   if (r.error) {
-    throw new Error(`detect-scenes: ffmpeg is unavailable at '${cmd}'. Install ffmpeg or pass --ffmpeg-cmd <path>.`);
+    // spawnSync reports its own limits via r.error, not by throwing — a tripped
+    // timeout/buffer means ffmpeg RAN, so "install ffmpeg" would be a lie.
+    const code = (r.error as NodeJS.ErrnoException).code;
+    if (code === "ETIMEDOUT") {
+      throw new Error(
+        `detect-scenes: scene detection timed out after ${timeoutMs / 1000}s on ${videoPath}. ` +
+          "Try a shorter or lower-resolution input.",
+      );
+    }
+    if (code === "ENOBUFS") {
+      const mib = maxBuffer / (1024 * 1024);
+      const cap = mib >= 1 ? `${Math.round(mib)} MiB` : `${maxBuffer}-byte`;
+      throw new Error(
+        `detect-scenes: ffmpeg output exceeded the ${cap} buffer on ${videoPath}. ` +
+          "Raise --threshold to emit fewer cut candidates.",
+      );
+    }
+    throw new Error(
+      `detect-scenes: ffmpeg is unavailable at '${cmd}'. Install ffmpeg or pass --ffmpeg-cmd <path>. (${
+        code ?? r.error.message
+      })`,
+    );
   }
   const stderr = typeof r.stderr === "string" ? r.stderr : "";
   if (r.status !== 0) {
     throw new Error(`detect-scenes: ffmpeg failed on ${videoPath}.\n${stderr.slice(-600)}`);
   }
-  const duration = parseFfmpegDuration(stderr);
-  const cuts = limitCuts(mergeCloseCuts(parseSceneCuts(stderr), minGap), opts.limit);
+  // Segment ends must come from the VIDEO stream's duration. The container
+  // header ("Duration:") is the LONGEST stream — when the audio track outlasts
+  // the video (common in screen recordings), it would point the final segment
+  // past the last video frame. ffprobe reads the real stream metadata; the
+  // centisecond-rounded header is only a fallback when ffprobe is unavailable,
+  // and duration_source says which one the report used.
+  const probe = probeMedia(videoPath, opts.ffprobeCmd ?? "ffprobe");
+  let duration: number | null;
+  let durationSource: SceneReport["duration_source"];
+  if (probe?.videoDurationUs != null) {
+    duration = probe.videoDurationUs / US;
+    durationSource = "video-stream";
+  } else {
+    duration = probe?.durationUs != null ? probe.durationUs / US : parseFfmpegDuration(stderr);
+    durationSource = duration === null ? null : "container";
+  }
+  // Drop cuts at/after the known end ONCE, so cuts[] and segments[] agree
+  // (buildSceneSegments applies the same bound internally).
+  const detected = parseSceneCuts(stderr).filter((c) => duration === null || c.time < duration);
+  const cuts = limitCuts(mergeCloseCuts(detected, minGap), opts.limit);
   return {
     video: videoPath,
     threshold,
@@ -198,6 +252,7 @@ export function detectScenes(videoPath: string, opts: SceneDetectOptions = {}):
     limit: opts.limit ?? null,
     duration,
     duration_us: duration === null ? null : Math.round(duration * US),
+    duration_source: durationSource,
     cuts: cuts.map((c) => ({
       time: c.time,
       time_us: Math.round(c.time * US),
diff --git a/test/detect-scenes.test.mjs b/test/detect-scenes.test.mjs
index f3b448c..7c1cd98 100644
--- a/test/detect-scenes.test.mjs
+++ b/test/detect-scenes.test.mjs
@@ -1,11 +1,12 @@
 import assert from "node:assert/strict";
 import { spawnSync } from "node:child_process";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { chmodSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { after, describe, it } from "node:test";
 import {
   buildSceneSegments,
+  detectScenes,
   limitCuts,
   mergeCloseCuts,
   parseFfmpegDuration,
@@ -16,6 +17,8 @@ import { spawnCli } from "./helpers/spawn-cli.mjs";
 
 const US = 1_000_000;
 const hasFfmpeg = spawnSync("ffmpeg", ["-version"], { encoding: "utf-8" }).status === 0;
+const hasFfprobe = spawnSync("ffprobe", ["-version"], { encoding: "utf-8" }).status === 0;
+const isWindows = process.platform === "win32"; // fake-ffmpeg tests use /bin/sh scripts
 
 // Three 1s solid-color scenes -> hard cuts at t=1 and t=2. Solid-color swaps
 // score exactly 0.4 on this ffmpeg, so tests pass an explicit --threshold 0.3
@@ -147,6 +150,14 @@ describe("detect-scenes — parsing + cut math (pure)", () => {
     assert.equal(timecode(1.5), "00:00:01.500");
     assert.equal(timecode(3723.042), "01:02:03.042");
   });
+
+  it("timecode carries millisecond round-up across minute/hour boundaries", () => {
+    // MPEG-TS 1/90000 timebase yields pts_time like 59.9996 — rounding the
+    // seconds field alone printed the out-of-range "00:00:60.000".
+    assert.equal(timecode(59.9996), "00:01:00.000");
+    assert.equal(timecode(3599.9999), "01:00:00.000");
+    assert.equal(timecode(59.9994), "00:00:59.999"); // rounds down: no carry
+  });
 });
 
 describe("detect-scenes — CLI", () => {
@@ -213,6 +224,120 @@ describe("detect-scenes — CLI", () => {
     assert.ok(json.json && Array.isArray(json.json.cuts), "--json must force JSON output");
   });
 
+  // Reviewer repro: 6s video track muxed with an 8s audio track. The container
+  // header reports 8s (longest stream), so the final segment used to be
+  // {start:4, end:8} — 2s past the last video frame.
+  it("ends the final segment at the video stream, not the longer audio track", {
+    skip: !hasFfmpeg || !hasFfprobe,
+  }, () => {
+    const s = setup();
+    after(s.cleanup);
+    const clip = join(s.dir, "longaudio.mp4");
+    const src = (color) => ["-f", "lavfi", "-i", `color=c=${color}:size=160x120:rate=15:duration=2`];
+    const r = spawnSync(
+      "ffmpeg",
+      [
+        "-y",
+        "-loglevel",
+        "error",
+        ...src("red"),
+        ...src("blue"),
+        ...src("green"),
+        "-f",
+        "lavfi",
+        "-i",
+        "anullsrc=r=8000:cl=mono:d=8",
+        "-filter_complex",
+        "[0:v][1:v][2:v]concat=n=3:v=1:a=0,format=yuv420p[v]",
+        "-map",
+        "[v]",
+        "-map",
+        "3:a",
+        "-c:a",
+        "aac",
+        clip,
+      ],
+      { encoding: "utf-8" },
+    );
+    assert.equal(r.status, 0, r.stderr);
+    const cli = spawnCli(["detect-scenes", clip, "--threshold", "0.3", "--min-gap", "0.5"]);
+    assert.equal(cli.status, 0, cli.stderr);
+    assert.equal(cli.json.duration_source, "video-stream");
+    assert.ok(
+      Math.abs(cli.json.duration - 6) < 0.2,
+      `duration ${cli.json.duration} must be ~6s (video), not 8s (container)`,
+    );
+    const last = cli.json.segments[cli.json.segments.length - 1];
+    assert.ok(Math.abs(last.end - 6) < 0.2, `final segment ends at ${last.end} — past the last video frame`);
+    assert.ok(last.end_us <= 6.2 * US, `final segment end_us ${last.end_us} overruns the video track`);
+  });
+
+  it("falls back to the container header when ffprobe is unavailable, and says so", { skip: isWindows }, () => {
+    const s = setup();
+    after(s.cleanup);
+    const placeholder = join(s.dir, "clip.mp4");
+    writeFileSync(placeholder, "");
+    // Fake ffmpeg emits a real-looking header + scene metadata; ffprobe is
+    // pointed at a nonexistent path to force the container fallback.
+    const fakeFfmpeg = join(s.dir, "fake-ffmpeg");
+    writeFileSync(fakeFfmpeg, `#!/bin/sh\ncat >&2 <<'EOF'\n${METADATA_STDERR}\nEOF\nexit 0\n`);
+    chmodSync(fakeFfmpeg, 0o755);
+    const r = spawnCli([
+      "detect-scenes",
+      placeholder,
+      "--min-gap",
+      "0.5",
+      "--ffmpeg-cmd",
+      fakeFfmpeg,
+      "--ffprobe-cmd",
+      "/nonexistent/ffprobe",
+    ]);
+    assert.equal(r.status, 0, r.stderr);
+    assert.equal(r.json.duration, 3);
+    assert.equal(r.json.duration_source, "container");
+    assert.equal(r.json.segments[r.json.segments.length - 1].end, 3);
+  });
+
+  // Reviewer repro: spawnSync reports a tripped timeout as r.error (code
+  // ETIMEDOUT, status null) — it used to be misreported as "install ffmpeg".
+  it("reports a timeout as a timeout, not as ffmpeg being unavailable", { skip: isWindows }, () => {
+    const s = setup();
+    after(s.cleanup);
+    const placeholder = join(s.dir, "clip.mp4");
+    writeFileSync(placeholder, "");
+    const slowFfmpeg = join(s.dir, "slow-ffmpeg");
+    writeFileSync(slowFfmpeg, "#!/bin/sh\nsleep 3\n");
+    chmodSync(slowFfmpeg, 0o755);
+    let err = null;
+    try {
+      detectScenes(placeholder, { ffmpegCmd: slowFfmpeg, timeoutMs: 250 });
+    } catch (e) {
+      err = e;
+    }
+    assert.ok(err, "expected detectScenes to throw on timeout");
+    assert.match(err.message, /timed out after 0\.25s/);
+    assert.doesNotMatch(err.message, /install ffmpeg|unavailable/i);
+  });
+
+  it("reports a maxBuffer overflow as such, not as ffmpeg being unavailable", { skip: isWindows }, () => {
+    const s = setup();
+    after(s.cleanup);
+    const placeholder = join(s.dir, "clip.mp4");
+    writeFileSync(placeholder, "");
+    const noisyFfmpeg = join(s.dir, "noisy-ffmpeg");
+    writeFileSync(noisyFfmpeg, "#!/bin/sh\nhead -c 200000 /dev/zero\n");
+    chmodSync(noisyFfmpeg, 0o755);
+    let err = null;
+    try {
+      detectScenes(placeholder, { ffmpegCmd: noisyFfmpeg, maxBufferBytes: 1024 });
+    } catch (e) {
+      err = e;
+    }
+    assert.ok(err, "expected detectScenes to throw on buffer overflow");
+    assert.match(err.message, /output exceeded/);
+    assert.doesNotMatch(err.message, /install ffmpeg|unavailable/i);
+  });
+
   it("fails with a clear error when the video is missing", () => {
     const r = spawnCli(["detect-scenes", "/nonexistent/video.mp4"]);
     assert.equal(r.status, 1);
diff --git a/test/probe.test.mjs b/test/probe.test.mjs
index e923326..357c361 100644
--- a/test/probe.test.mjs
+++ b/test/probe.test.mjs
@@ -100,11 +100,27 @@ describe("probe: full media metadata", () => {
     assert.equal(parsed.width, 1080);
     assert.equal(parsed.height, 1920);
     assert.equal(parsed.durationUs, 12_500_000);
+    // no per-stream duration in this fixture -> video-stream duration unknown
+    assert.equal(parsed.videoDurationUs, null);
     assert.ok(Math.abs(parsed.fps - 29.97) < 0.01);
     assert.equal(parsed.audioChannels, 2);
     assert.equal(parsed.videoCodec, "h264");
     assert.equal(parsed.audioCodec, "aac");
   });
+
+  it("reads the video stream's own duration separately from the container's", () => {
+    const parsed = parseMediaProbe(
+      JSON.stringify({
+        streams: [
+          { codec_type: "video", codec_name: "h264", width: 160, height: 120, duration: "6.000000" },
+          { codec_type: "audio", codec_name: "aac", channels: 1, duration: "8.000000" },
+        ],
+        format: { duration: "8.000000" },
+      }),
+    );
+    assert.equal(parsed.durationUs, 8_000_000, "container duration = longest stream");
+    assert.equal(parsed.videoDurationUs, 6_000_000, "video stream duration must not include the audio tail");
+  });
 });
 
 describe("probe: normalizeRotation", () => {

From ea1bc0ec17d26addaabf65bcb3c5482f145a2d98 Mon Sep 17 00:00:00 2001
From: Rene Zander <renezander030@gmail.com>
Date: Wed, 8 Jul 2026 12:22:23 +0000
Subject: [PATCH 14/17] fix(preset): enforce flag precedence, validate schema,
 honor dry-run

- Explicit --color/--font-size now also override preset text_ranges, so
  karaoke/highlight blocks no longer re-stamp their captured colours/sizes
  over the flag values (documented "flags override preset" contract).
- parsePreset validates transform/bubble/text_ranges shapes and style field
  value types, rejecting malformed presets with a clear error instead of
  writing garbage (e.g. transform:{}) into the draft.
- Applying a rangeless preset onto a multi-range segment now collapses the
  leftover range blocks to the single uniform preset style.
- make-preset gates its writeFileSync on isDryRun() and reports `written`.
---
 src/index.ts  |  23 +++++++--
 src/preset.ts | 127 ++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 147 insertions(+), 3 deletions(-)

diff --git a/src/index.ts b/src/index.ts
index 4ca520f..463493b 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -431,7 +431,10 @@ Templates:
              (font, colors, shadow/border/background box, alignment/position,
              bubble, text ranges). Apply with --preset on add-text,
              text-style, or caption; explicit CLI flags override preset
-             values.
+             values (including per-range colours/sizes for the span they
+             cover). A preset applies in full: a preset WITHOUT text ranges
+             resets the target to one uniform style, clearing any existing
+             karaoke/highlight ranges. Honors --dry-run (no file written).
   templates
              Show available templates in the template library.
              Use -H for a table.
@@ -1575,6 +1578,17 @@ function presetWithFlagOverrides(preset: TextStylePreset, flags: Flags): TextSty
     if (flags.x !== undefined) p.transform.x = flags.x;
     if (flags.y !== undefined) p.transform.y = flags.y;
   }
+  // --color / --font-size cover the whole cue, so they must also win over any
+  // preset text_ranges (karaoke/highlight blocks). Otherwise applyTextPreset's
+  // setTextRanges pass runs LAST and re-stamps the preset's per-range colours
+  // and sizes over the flag values just mirrored into styles[0] — silently
+  // defeating the documented "explicit flags override preset values" contract.
+  if (p.text_ranges && p.text_ranges.length > 0) {
+    for (const r of p.text_ranges) {
+      if (flags.color !== undefined) r.font_color = flags.color;
+      if (flags.fontSize !== undefined) r.font_size = flags.fontSize;
+    }
+  }
   return p;
 }
 
@@ -1987,8 +2001,11 @@ function cmdMakePreset(draft: Draft, positional: string[], flags: Flags): void {
   if (!flags.out)
     die("Missing --out <path>. Usage: capcut make-preset <project> <text-segment-id> --out <preset.json>");
   const { preset, segmentId, materialId, captured } = extractTextPreset(draft, segId);
-  writeFileSync(flags.out, JSON.stringify(preset, null, 2), "utf-8");
-  out({ ok: true, segment_id: segmentId, material_id: materialId, captured, out: flags.out }, flags);
+  // Honor --dry-run: preview the extraction without touching the preset file
+  // (which may be an existing preset the user only meant to inspect).
+  const written = !isDryRun();
+  if (written) writeFileSync(flags.out, JSON.stringify(preset, null, 2), "utf-8");
+  out({ ok: true, segment_id: segmentId, material_id: materialId, captured, out: flags.out, written }, flags);
 }
 
 // --- Phase 4: multi-style text ranges ---
diff --git a/src/preset.ts b/src/preset.ts
index e49b577..25c15eb 100644
--- a/src/preset.ts
+++ b/src/preset.ts
@@ -134,6 +134,118 @@ export function extractTextPreset(
   return { preset, segmentId: seg.id, materialId: mat.id, captured };
 }
 
+// Style fields whose stored type is fixed across CapCut versions. A preset is a
+// portable, hand-editable JSON file: reject a wrong-typed value up front rather
+// than stamp e.g. font_size:"huge" onto the material and corrupt the draft.
+const NUMERIC_STYLE_FIELDS = [
+  "font_size",
+  "alignment",
+  "typesetting",
+  "letter_spacing",
+  "line_spacing",
+  "text_alpha",
+  "shadow_alpha",
+  "shadow_angle",
+  "shadow_distance",
+  "shadow_smoothing",
+  "border_width",
+  "border_alpha",
+  "background_alpha",
+  "background_style",
+  "background_round_radius",
+  "background_width",
+  "background_height",
+  "background_horizontal_offset",
+  "background_vertical_offset",
+];
+const STRING_STYLE_FIELDS = [
+  "text_color",
+  "shadow_color",
+  "border_color",
+  "background_color",
+  "font_id",
+  "font_name",
+  "font_path",
+  "font_resource_id",
+];
+const BOOLEAN_STYLE_FIELDS = ["bold", "italic", "underline", "has_shadow", "has_border", "has_text_shadow_config"];
+
+function validatePresetStyle(style: Record<string, unknown>, source: string): void {
+  for (const f of NUMERIC_STYLE_FIELDS) {
+    const v = style[f];
+    if (v !== undefined && (typeof v !== "number" || !Number.isFinite(v))) {
+      throw new Error(`Preset "style.${f}" must be a finite number, got ${JSON.stringify(v)}: ${source}`);
+    }
+  }
+  for (const f of STRING_STYLE_FIELDS) {
+    if (style[f] !== undefined && typeof style[f] !== "string") {
+      throw new Error(`Preset "style.${f}" must be a string, got ${JSON.stringify(style[f])}: ${source}`);
+    }
+  }
+  for (const f of BOOLEAN_STYLE_FIELDS) {
+    if (style[f] !== undefined && typeof style[f] !== "boolean") {
+      throw new Error(`Preset "style.${f}" must be a boolean, got ${JSON.stringify(style[f])}: ${source}`);
+    }
+  }
+}
+
+function validateTransform(t: unknown, source: string): void {
+  if (t === null || typeof t !== "object" || Array.isArray(t)) {
+    throw new Error(`Preset "transform" must be an object { x: number, y: number }: ${source}`);
+  }
+  const tr = t as Record<string, unknown>;
+  if (typeof tr.x !== "number" || !Number.isFinite(tr.x) || typeof tr.y !== "number" || !Number.isFinite(tr.y)) {
+    throw new Error(`Preset "transform" requires finite numeric "x" and "y": ${source}`);
+  }
+}
+
+function validateBubble(b: unknown, source: string): void {
+  if (b === null || typeof b !== "object" || Array.isArray(b)) {
+    throw new Error(`Preset "bubble" must be an object { effect_id, resource_id }: ${source}`);
+  }
+  const bu = b as Record<string, unknown>;
+  if (typeof bu.effect_id !== "string" || !bu.effect_id || typeof bu.resource_id !== "string" || !bu.resource_id) {
+    throw new Error(`Preset "bubble" requires non-empty string "effect_id" and "resource_id": ${source}`);
+  }
+}
+
+function validateTextRanges(ranges: unknown, source: string): void {
+  if (!Array.isArray(ranges)) {
+    throw new Error(`Preset "text_ranges" must be an array: ${source}`);
+  }
+  ranges.forEach((r, i) => {
+    if (r === null || typeof r !== "object" || Array.isArray(r)) {
+      throw new Error(`Preset "text_ranges[${i}]" must be an object: ${source}`);
+    }
+    const range = r as Record<string, unknown>;
+    if (!Number.isInteger(range.start) || !Number.isInteger(range.end)) {
+      throw new Error(`Preset "text_ranges[${i}]" requires integer "start" and "end": ${source}`);
+    }
+    const start = range.start as number;
+    const end = range.end as number;
+    if (start < 0) throw new Error(`Preset "text_ranges[${i}]" start must be >= 0: ${source}`);
+    if (end <= start)
+      throw new Error(`Preset "text_ranges[${i}]" end must be > start (got [${start},${end})): ${source}`);
+    if (range.font_color !== undefined && typeof range.font_color !== "string") {
+      throw new Error(`Preset "text_ranges[${i}].font_color" must be a string: ${source}`);
+    }
+    if (range.font_size !== undefined && (typeof range.font_size !== "number" || !Number.isFinite(range.font_size))) {
+      throw new Error(`Preset "text_ranges[${i}].font_size" must be a number: ${source}`);
+    }
+    if (
+      range.font_alpha !== undefined &&
+      (typeof range.font_alpha !== "number" || !Number.isFinite(range.font_alpha))
+    ) {
+      throw new Error(`Preset "text_ranges[${i}].font_alpha" must be a number: ${source}`);
+    }
+    for (const f of ["bold", "italic", "underline"] as const) {
+      if (range[f] !== undefined && typeof range[f] !== "boolean") {
+        throw new Error(`Preset "text_ranges[${i}].${f}" must be a boolean: ${source}`);
+      }
+    }
+  });
+}
+
 export function parsePreset(raw: string, source: string): TextStylePreset {
   let parsed: unknown;
   try {
@@ -156,6 +268,10 @@ export function parsePreset(raw: string, source: string): TextStylePreset {
   if (p.style === null || typeof p.style !== "object" || Array.isArray(p.style)) {
     throw new Error(`Preset "style" must be an object: ${source}`);
   }
+  validatePresetStyle(p.style as Record<string, unknown>, source);
+  if (p.transform !== undefined) validateTransform(p.transform, source);
+  if (p.bubble !== undefined) validateBubble(p.bubble, source);
+  if (p.text_ranges !== undefined) validateTextRanges(p.text_ranges, source);
   return p as unknown as TextStylePreset;
 }
 
@@ -211,6 +327,17 @@ export function applyTextPreset(
         path: preset.style.font_path,
       };
     }
+    // A preset "applies in full". A rangeless preset describes ONE uniform look,
+    // so applying it onto a segment that still carries multiple range blocks
+    // (leftover karaoke/highlight styling) must collapse those blocks to the
+    // single preset style — otherwise the trailing base-style chunk keeps its
+    // old size/colour while the material/output claim the new style.
+    const hasPresetRanges = Array.isArray(preset.text_ranges) && preset.text_ranges.length > 0;
+    if (!hasPresetRanges && content.styles && content.styles.length > 1) {
+      const byteLen = Buffer.from(content.text ?? "", "utf16le").length;
+      base.range = [0, byteLen];
+      content.styles = [base];
+    }
     mat.content = JSON.stringify(content);
   }
 

From dd1b8870e9e4c70d8d8a1f8142c73961a4d9b20d Mon Sep 17 00:00:00 2001
From: Rene Zander <renezander030@gmail.com>
Date: Wed, 8 Jul 2026 12:23:16 +0000
Subject: [PATCH 15/17] test(preset): cover flag precedence, schema validation,
 collapse, dry-run

Regression tests for the four preset findings: flags overriding captured
text_ranges (and preservation without flags), rejection of malformed
transform/style/text_ranges/bubble shapes (plus a valid one still applying),
rangeless-preset collapse of a multi-range segment (and a ranged preset
preserving blocks), and make-preset honoring --dry-run.
---
 test/make-preset.test.mjs | 246 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 246 insertions(+)

diff --git a/test/make-preset.test.mjs b/test/make-preset.test.mjs
index 18d0f0d..780fb2d 100644
--- a/test/make-preset.test.mjs
+++ b/test/make-preset.test.mjs
@@ -247,3 +247,249 @@ describe("capcut make-preset errors", () => {
     assert.match(r.stderr, /not found/i);
   });
 });
+
+// --- Regression: code-review findings v0.13.0 ---
+
+// Pull the rendered content style blocks (CapCut renders from these, not the
+// material fields) for a segment's text material.
+function contentStyles(draftPath, materialId) {
+  const draft = loadDraft(draftPath);
+  const mat = draft.materials.texts.find((t) => t.id === materialId);
+  return JSON.parse(mat.content).styles;
+}
+
+function solidColor(block) {
+  return block.fill.content.solid.color;
+}
+
+// Finding 1: preset text_ranges must not defeat explicit --color/--font-size.
+describe("--preset: explicit flags override preset text_ranges (karaoke)", () => {
+  const src = tmpDraft();
+  const out = tmpDir();
+  const presetPath = join(out.dir, "karaoke.json");
+  after(() => {
+    src.cleanup();
+    out.cleanup();
+  });
+
+  it("builds a karaoke preset carrying per-range colours/sizes", () => {
+    const added = spawnCli(["add-text", src.path, "0s", "3s", "hello world hi"]);
+    assert.equal(added.status, 0, `stderr: ${added.stderr}`);
+    const styles = JSON.stringify([{ start: 6, end: 11, font_color: "#FFD700", font_size: 24, bold: true }]);
+    const ranged = spawnCli(["text-ranges", src.path, added.json.segment_id, "--styles", styles]);
+    assert.equal(ranged.status, 0, `stderr: ${ranged.stderr}`);
+    const made = spawnCli(["make-preset", src.path, added.json.segment_id, "--out", presetPath]);
+    assert.equal(made.status, 0, `stderr: ${made.stderr}`);
+    const preset = JSON.parse(readFileSync(presetPath, "utf-8"));
+    assert.ok(Array.isArray(preset.text_ranges) && preset.text_ranges.length > 1, "preset captured ranges");
+  });
+
+  it("flag colour/size win over EVERY captured range block", () => {
+    const dst = tmpDraft();
+    try {
+      const r = spawnCli([
+        "add-text",
+        dst.path,
+        "0s",
+        "3s",
+        "brand new caption",
+        "--preset",
+        presetPath,
+        "--color",
+        "#00FF00",
+        "--font-size",
+        "30",
+      ]);
+      assert.equal(r.status, 0, `stderr: ${r.stderr}`);
+      const draft = loadDraft(dst.path);
+      const mat = draft.materials.texts.find((t) => t.id === r.json.material_id);
+      assert.equal(mat.text_color, "#00FF00");
+      assert.equal(mat.font_size, 30);
+      // No range block may keep the preset's gold/24 look.
+      for (const block of contentStyles(dst.path, r.json.material_id)) {
+        assert.equal(block.size, 30, "flag size overrides preset range size");
+        assert.deepEqual(solidColor(block), [0, 1, 0], "flag colour overrides preset range colour");
+      }
+    } finally {
+      dst.cleanup();
+    }
+  });
+
+  it("without flags, the preset's per-range styling is preserved", () => {
+    const dst = tmpDraft();
+    try {
+      const r = spawnCli(["add-text", dst.path, "0s", "3s", "brand new caption", "--preset", presetPath]);
+      assert.equal(r.status, 0, `stderr: ${r.stderr}`);
+      const gold = contentStyles(dst.path, r.json.material_id).find((b) => b.bold === true);
+      assert.ok(gold, "gold highlight block survived");
+      assert.equal(gold.size, 24, "preset range size kept when no flag given");
+    } finally {
+      dst.cleanup();
+    }
+  });
+});
+
+// Finding 2: schema validation of preset sub-objects.
+describe("--preset: schema validation rejects malformed sub-objects", () => {
+  const fix = tmpDraft();
+  const out = tmpDir();
+  after(() => {
+    fix.cleanup();
+    out.cleanup();
+  });
+
+  function applyBadPreset(preset) {
+    const p = join(out.dir, `bad-${Math.random().toString(36).slice(2)}.json`);
+    writeFileSync(p, JSON.stringify(preset));
+    return spawnCli(["add-text", fix.path, "0s", "2s", "abc", "--preset", p]);
+  }
+
+  it("rejects a transform that is an array, not { x, y }", () => {
+    const r = applyBadPreset({ capcutCliPreset: 1, style: {}, transform: [0.1, 0.2] });
+    assert.notEqual(r.status, 0);
+    assert.match(r.stderr, /transform/i);
+  });
+
+  it("rejects a transform with non-numeric x/y", () => {
+    const r = applyBadPreset({ capcutCliPreset: 1, style: {}, transform: { x: "0.5", y: 0.1 } });
+    assert.notEqual(r.status, 0);
+    assert.match(r.stderr, /transform/i);
+  });
+
+  it("rejects a string in a numeric style field", () => {
+    const r = applyBadPreset({ capcutCliPreset: 1, style: { font_size: "huge" } });
+    assert.notEqual(r.status, 0);
+    assert.match(r.stderr, /font_size/i);
+  });
+
+  it("rejects text_ranges that is not an array", () => {
+    const r = applyBadPreset({ capcutCliPreset: 1, style: {}, text_ranges: "nope" });
+    assert.notEqual(r.status, 0);
+    assert.match(r.stderr, /text_ranges/i);
+  });
+
+  it("rejects a text range with end <= start", () => {
+    const r = applyBadPreset({ capcutCliPreset: 1, style: {}, text_ranges: [{ start: 5, end: 2 }] });
+    assert.notEqual(r.status, 0);
+    assert.match(r.stderr, /text_ranges/i);
+  });
+
+  it("rejects a bubble missing resource_id", () => {
+    const r = applyBadPreset({ capcutCliPreset: 1, style: {}, bubble: { effect_id: "x" } });
+    assert.notEqual(r.status, 0);
+    assert.match(r.stderr, /bubble/i);
+  });
+
+  it("a well-formed transform + text_ranges preset still applies", () => {
+    const good = join(out.dir, "good.json");
+    writeFileSync(
+      good,
+      JSON.stringify({
+        capcutCliPreset: 1,
+        style: { font_size: 24 },
+        transform: { x: 0.1, y: 0.2 },
+        text_ranges: [{ start: 0, end: 3, font_color: "#00FF00" }],
+      }),
+    );
+    const r = spawnCli(["add-text", fix.path, "0s", "2s", "abcdef", "--preset", good]);
+    assert.equal(r.status, 0, `stderr: ${r.stderr}`);
+    const seg = loadDraft(fix.path)
+      .tracks.flatMap((t) => t.segments)
+      .find((s) => s.id === r.json.segment_id);
+    assert.deepEqual(seg.clip.transform, { x: 0.1, y: 0.2 });
+  });
+});
+
+// Finding 3: rangeless preset onto an already-multi-range segment.
+describe("--preset: rangeless preset onto a multi-range segment", () => {
+  const fix = tmpDraft();
+  const out = tmpDir();
+  after(() => {
+    fix.cleanup();
+    out.cleanup();
+  });
+
+  function multiRangeSegment(text) {
+    const added = spawnCli(["add-text", fix.path, "0s", "3s", text]);
+    assert.equal(added.status, 0, `stderr: ${added.stderr}`);
+    const styles = JSON.stringify([{ start: 6, end: 11, font_color: "#FFD700", font_size: 24, bold: true }]);
+    const ranged = spawnCli(["text-ranges", fix.path, added.json.segment_id, "--styles", styles]);
+    assert.equal(ranged.status, 0, `stderr: ${ranged.stderr}`);
+    assert.ok(contentStyles(fix.path, added.json.material_id).length > 1, "segment is multi-range");
+    return added.json;
+  }
+
+  it("a rangeless preset collapses the segment to one uniform style", () => {
+    const seg = multiRangeSegment("hello world hi");
+    const p = join(out.dir, "plain.json");
+    writeFileSync(p, JSON.stringify({ capcutCliPreset: 1, style: { font_size: 40, text_color: "#0000FF" } }));
+    const r = spawnCli(["text-style", fix.path, seg.segment_id, "--preset", p]);
+    assert.equal(r.status, 0, `stderr: ${r.stderr}`);
+    const styles = contentStyles(fix.path, seg.material_id);
+    assert.equal(styles.length, 1, "all range blocks collapsed to one");
+    assert.equal(styles[0].size, 40);
+    assert.deepEqual(solidColor(styles[0]), [0, 0, 1]);
+    const byteLen = Buffer.from("hello world hi", "utf16le").length;
+    assert.deepEqual(styles[0].range, [0, byteLen], "the single block spans the whole text");
+  });
+
+  it("a preset WITH ranges keeps multiple blocks (no collapse)", () => {
+    const seg = multiRangeSegment("hello world hi");
+    const p = join(out.dir, "ranged.json");
+    writeFileSync(
+      p,
+      JSON.stringify({
+        capcutCliPreset: 1,
+        style: { font_size: 18 },
+        text_ranges: [{ start: 0, end: 5, font_color: "#FF0000" }],
+      }),
+    );
+    const r = spawnCli(["text-style", fix.path, seg.segment_id, "--preset", p]);
+    assert.equal(r.status, 0, `stderr: ${r.stderr}`);
+    assert.ok(contentStyles(fix.path, seg.material_id).length > 1, "ranged preset preserves range blocks");
+  });
+});
+
+// Finding 4: make-preset must honour --dry-run.
+describe("make-preset --dry-run", () => {
+  const fix = tmpDraft();
+  const out = tmpDir();
+  let segId;
+  after(() => {
+    fix.cleanup();
+    out.cleanup();
+  });
+
+  it("sets up a text segment to extract", () => {
+    const added = spawnCli(["add-text", fix.path, "0s", "3s", "preview me", "--font-size", "22"]);
+    assert.equal(added.status, 0, `stderr: ${added.stderr}`);
+    segId = added.json.segment_id;
+  });
+
+  it("does not write the preset file under --dry-run", () => {
+    const p = join(out.dir, "dry.json");
+    const r = spawnCli(["make-preset", fix.path, segId, "--out", p, "--dry-run"]);
+    assert.equal(r.status, 0, `stderr: ${r.stderr}`);
+    assert.equal(r.json.dryRun, true);
+    assert.equal(r.json.written, false, "output reports the file was not written");
+    assert.equal(existsSync(p), false, "no file created on disk");
+  });
+
+  it("does not clobber an existing preset under --dry-run", () => {
+    const p = join(out.dir, "existing.json");
+    const sentinel = '{"sentinel":true}';
+    writeFileSync(p, sentinel);
+    const r = spawnCli(["make-preset", fix.path, segId, "--out", p, "--dry-run"]);
+    assert.equal(r.status, 0, `stderr: ${r.stderr}`);
+    assert.equal(readFileSync(p, "utf-8"), sentinel, "existing file left untouched");
+  });
+
+  it("writes the preset file for a real (non-dry) run", () => {
+    const p = join(out.dir, "real.json");
+    const r = spawnCli(["make-preset", fix.path, segId, "--out", p]);
+    assert.equal(r.status, 0, `stderr: ${r.stderr}`);
+    assert.equal(r.json.written, true);
+    assert.ok(existsSync(p), "file written on disk");
+    assert.equal(JSON.parse(readFileSync(p, "utf-8")).capcutCliPreset, 1);
+  });
+});

From a43aa7021e8157bbd5b4997a1f3312312f1c2be5 Mon Sep 17 00:00:00 2001
From: Rene Zander <renezander030@gmail.com>
Date: Wed, 8 Jul 2026 12:23:50 +0000
Subject: [PATCH 16/17] fix(cli): scope new release flags to the commands that
 declare them

parseFlags is a single global pass; the flags added this release
(--threshold, --min-gap, --limit, --json, --granularity, --format,
--easing, --preset, --apply) were consumed on every command, silently
stripping flag-like tokens from free-text positionals (e.g. an add-text
body containing '--limit 5'). Scope each of these flags to the commands
that declare them via command-specs; on any other command they fall
through to the positional stream verbatim, restoring pre-release
behaviour. Flags that master already parsed globally are unchanged.

Adds regression tests both directions: free-text preservation on
non-declaring commands and continued parsing/validation on the
declaring command.
---
 src/command-specs.ts       | 30 ++++++++++++++
 src/index.ts               | 20 +++++++++-
 test/flag-scoping.test.mjs | 81 ++++++++++++++++++++++++++++++++++++++
 3 files changed, 130 insertions(+), 1 deletion(-)
 create mode 100644 test/flag-scoping.test.mjs

diff --git a/src/command-specs.ts b/src/command-specs.ts
index 26ae987..2ef4e62 100644
--- a/src/command-specs.ts
+++ b/src/command-specs.ts
@@ -423,6 +423,36 @@ const optionsByCommand: Record<string, OptionSpec[]> = {
 };
 optionsByCommand["image-anim"] = optionsByCommand["text-anim"];
 
+// Flags introduced in this release. parseFlags is a single flat global pass, so
+// a value-consuming flag added here would otherwise be stripped from ANY
+// command's free-text positionals (e.g. an add-text body containing the
+// substring "--limit 5"). These are scoped to the commands that declare them:
+//   --easing            -> keyframe
+//   --granularity, --format -> export-srt
+//   --preset            -> add-text, text-style, caption
+//   --apply             -> sync-timelines
+//   --threshold, --min-gap, --limit, --json -> detect-scenes
+// Everywhere else they fall through to the positional stream verbatim, matching
+// pre-release behaviour where these tokens were unknown and preserved.
+export const RELEASE_SCOPED_FLAGS: ReadonlySet<string> = new Set([
+  "--apply",
+  "--easing",
+  "--format",
+  "--granularity",
+  "--json",
+  "--limit",
+  "--min-gap",
+  "--preset",
+  "--threshold",
+]);
+
+/** True when `command` declares `flag` among its command-specific options. */
+export function commandDeclaresFlag(command: string | undefined, flag: string): boolean {
+  if (command === undefined) return false;
+  const opts = optionsByCommand[command];
+  return opts?.some((o) => o.flags.includes(flag)) ?? false;
+}
+
 const mutating = new Set([
   "set-text",
   "shift",
diff --git a/src/index.ts b/src/index.ts
index 4ca520f..3c2e508 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -7,7 +7,14 @@ import { fileURLToPath } from "node:url";
 import { parseAss } from "./ass.js";
 import { captionDraft } from "./caption.js";
 import { removeChroma, setChroma } from "./chroma.js";
-import { buildCommandSpecs, completionWords, GLOBAL_OPTION_SPECS, renderCommandIndex } from "./command-specs.js";
+import {
+  buildCommandSpecs,
+  commandDeclaresFlag,
+  completionWords,
+  GLOBAL_OPTION_SPECS,
+  RELEASE_SCOPED_FLAGS,
+  renderCommandIndex,
+} from "./command-specs.js";
 import { type CompileSpec, compileDraft, parseSpec, planCompile } from "./compile.js";
 import type {
   ImageAnimOptions,
@@ -764,8 +771,19 @@ function fishCompletion(): string {
 function parseFlags(args: string[]): { positional: string[]; flags: Flags } {
   const positional: string[] = [];
   const flags: Flags = { human: false, quiet: false, batch: false };
+  // The subcommand is the first non-flag token (matches how dispatch reads
+  // positional[0]). Used to scope flags added in this release to the commands
+  // that declare them.
+  const command = args.find((a) => a.length > 0 && !a.startsWith("-"));
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
+    // A flag added in this release that the current command does not declare is
+    // left in the positional stream verbatim, so a value-consuming flag can
+    // never strip tokens from another command's free-text arguments.
+    if (RELEASE_SCOPED_FLAGS.has(a) && !commandDeclaresFlag(command, a)) {
+      positional.push(a);
+      continue;
+    }
     if (a === "-H" || a === "--human") flags.human = true;
     else if (a === "-v" || a === "--version") flags.version = true;
     else if (a === "-q" || a === "--quiet") flags.quiet = true;
diff --git a/test/flag-scoping.test.mjs b/test/flag-scoping.test.mjs
new file mode 100644
index 0000000..f8330a3
--- /dev/null
+++ b/test/flag-scoping.test.mjs
@@ -0,0 +1,81 @@
+import assert from "node:assert/strict";
+import { join } from "node:path";
+import { after, before, describe, it } from "node:test";
+import { spawnCli } from "./helpers/spawn-cli.mjs";
+import { tmpDir, tmpDraft } from "./helpers/tmp-draft.mjs";
+
+// Regression: flags added in this release (--threshold, --min-gap, --limit,
+// --json, --granularity, --format, --easing, --preset, --apply) are parsed by
+// the single global parseFlags pass. They must be scoped to the commands that
+// declare them, so a free-text positional that happens to contain a flag-like
+// substring is preserved verbatim instead of being silently stripped.
+
+describe("flag scoping — free-text positionals survive release flags (regression)", () => {
+  const src = tmpDraft();
+  after(() => src.cleanup());
+
+  it("add-text keeps a '--limit 5' substring inside the text verbatim", () => {
+    const r = spawnCli(["add-text", src.path, "0s", "2s", "New", "Year", "--limit", "5", "drinks"]);
+    assert.equal(r.status, 0, `stderr: ${r.stderr}`);
+    // On the regression the value token "5" was consumed too, yielding
+    // "New Year drinks". The whole run of tokens must be preserved.
+    assert.equal(r.json.text, "New Year --limit 5 drinks");
+  });
+
+  it("add-text preserves every new-in-release flag token that it does not declare", () => {
+    const words = [
+      "keep",
+      "--json",
+      "--apply",
+      "--easing",
+      "linear",
+      "--format",
+      "vtt",
+      "--threshold",
+      "0.4",
+      "--min-gap",
+      "2",
+      "--granularity",
+      "word",
+      "end",
+    ];
+    const r = spawnCli(["add-text", src.path, "0s", "2s", ...words]);
+    assert.equal(r.status, 0, `stderr: ${r.stderr}`);
+    assert.equal(r.json.text, words.join(" "));
+  });
+
+  it("a '--format json'-looking substring no longer hard-errors on an unrelated command", () => {
+    // --format is only declared by export-srt; add-text must treat it as text
+    // rather than validating it against srt|vtt (which used to throw).
+    const r = spawnCli(["add-text", src.path, "0s", "2s", "render", "--format", "json"]);
+    assert.equal(r.status, 0, `stderr: ${r.stderr}`);
+    assert.equal(r.json.text, "render --format json");
+  });
+});
+
+describe("flag scoping — scoped flags still work on the command that declares them", () => {
+  const t = tmpDir();
+  after(() => t.cleanup());
+
+  let project;
+  before(() => {
+    const init = spawnCli(["init", "scoped", "--drafts", t.dir]);
+    assert.equal(init.status, 0, `stderr: ${init.stderr}`);
+    project = join(t.dir, "scoped");
+    const srt = "1\n00:00:01,000 --> 00:00:04,000\nhello brave world\n\n2\n00:00:05,000 --> 00:00:06,000\nbye\n";
+    const imported = spawnCli(["import-srt", project, "-"], { input: srt });
+    assert.equal(imported.status, 0, `stderr: ${imported.stderr}`);
+  });
+
+  it("export-srt --format vtt is consumed and applied (value flag on its own command)", () => {
+    const r = spawnCli(["export-srt", project, "--format", "vtt"]);
+    assert.equal(r.status, 0, `stderr: ${r.stderr}`);
+    assert.match(r.stdout, /^WEBVTT\n\n/);
+  });
+
+  it("export-srt --granularity rejects an invalid value (validation still runs on its own command)", () => {
+    const r = spawnCli(["export-srt", project, "--granularity", "sentence"]);
+    assert.notEqual(r.status, 0);
+    assert.match(r.stderr, /--granularity must be line\|word/);
+  });
+});

From 36a47d778d399474fe1d3958e077f34c42421d9a Mon Sep 17 00:00:00 2001
From: Rene Zander <renezander030@gmail.com>
Date: Wed, 8 Jul 2026 12:28:07 +0000
Subject: [PATCH 17/17] docs(release): finalize v0.13.0 changelog and command
 reference

---
 CHANGELOG.md                | 13 +++++++++----
 docs/command-reference.json | 22 ++++++++++++++++------
 docs/command-reference.md   |  2 +-
 3 files changed, 26 insertions(+), 11 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b9dfb75..1926c1e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,13 +8,18 @@ Six features in one release — the top of the opportunity backlog, bundled. Two
 
 ### Added
 
-- `sync-timelines <project> [--apply] [--force-write]` — reconcile a CapCut >= 8.7 draft whose `template-2.tmp` / `draft_info.json` timeline mirror has drifted from `draft_content.json`, so CLI edits are honored by the app instead of silently ignored. `draft_content.json` is always canonical. Plan-only by default (per-target drift report, including `draft_info.json` GUID reconciliation for the pre-open mirror case); `--apply` writes through the existing transactional multi-target save (temp files, `.bak` backups, rollback, optimistic-concurrency check). Refuses to write while the editor is running unless `--force-write`, no-ops with exit 0 when all targets agree, and reports an unreadable (binary/encrypted) `template-2.tmp` as unreconcilable instead of pretending success. `diagnose` now points to `sync-timelines` as the remedy instead of deferring to issue #35. Closes #39.
-- `lint <project> --fix` — auto-repair mechanically-fixable draft defects, now four codes: `cue-too-long` (trims over-long captions to the configured cap), `caption-overlap` (shortens overlapping pairs so each ends where the next begins), `line-too-long` (greedy word wrap that swaps spaces for newlines 1:1, keeping styled-range byte offsets valid; never splits words), and `caption-gap-too-small` (pulls the earlier caption's end back to restore the minimum gap; never moves starts, never creates a new overlap). Writes atomically with a `.bak` snapshot; combine with `--dry-run` to preview. `missing-material` and `missing-file` stay report-only deliberately: the only mechanical repairs would delete user timeline content or act on host-dependent paths. Closes #40.
-- `lint` — new report-only rule `unknown-effect-slug` (warning severity): flags effect/filter/animation resource ids in the draft that are not in the bundled enum table, surfacing them before CapCut silently drops them (the silent-failure mode reported across ecosystem tools, e.g. GuanYixuan/pyCapCut#12).
+- `sync-timelines <project-dir> [--apply] [--force-write]` — reconcile a CapCut >= 8.7 draft whose `template-2.tmp` / `draft_info.json` timeline mirror has drifted from `draft_content.json`, so CLI edits are honored by the app instead of silently ignored. `draft_content.json` is always canonical and is treated read-only. Accepts only a project directory or its `draft_content.json` (any other filename exits 1). Plan-only by default: the per-target drift report includes each mirror's mtime plus `newer_mirrors` / `canonical_stale`, and warns when `draft_content.json` is older than a drifted mirror (you would overwrite newer edits). `--apply` refuses that direction unless you add `--force-write` (exit 1), then rewrites **only** the drifted mirrors — the canonical file is never re-sorted or backed up, and in-sync mirrors are left untouched; `reconciled` / `backups` list exactly the files written. No-ops with exit 0 when all targets already agree. An unreadable (binary/encrypted) mirror is reported unreconcilable (`ok:false`, `in_sync:false`, exit 2) and stays idempotent on re-run instead of pretending success. `--apply --dry-run` reports the plan only (`would_reconcile`, `reconciled: []`). `diagnose` now recommends the plan form (with a back-up caution) instead of deferring to issue #35. Closes #39.
+- `lint <project> --fix` — auto-repair mechanically-fixable draft defects, now four codes: `cue-too-long` (trims over-long captions to the configured cap), `caption-overlap` (shortens overlapping pairs so each ends where the next begins), `line-too-long` (greedy word wrap that swaps spaces for newlines 1:1, keeping styled-range byte offsets valid; never splits words — instances the wrap cannot actually fix, i.e. space-less/CJK text and over-cap single words, are stamped `fixable:false`), and `caption-gap-too-small` (pulls the earlier caption's end back to restore the minimum gap; never moves starts, never creates a new overlap). The gap repair honors a hard floor — exported `MIN_CAPTION_DURATION_US = 100_000` (100ms) — so a shrink that would land a caption below the floor is skipped and stamped `fixable:false` for that instance instead of collapsing it. Writes atomically with a `.bak` snapshot; combine with `--dry-run` to preview. `missing-material` and `missing-file` stay report-only deliberately: the only mechanical repairs would delete user timeline content or act on host-dependent paths. Closes #40.
+- `lint` — new report-only rule `unknown-effect-slug` (**info** severity, exit 0): flags effect/filter/animation resource ids in the draft that are not in the bundled enum table, surfacing them before CapCut silently drops them (the silent-failure mode reported across ecosystem tools, e.g. GuanYixuan/pyCapCut#12). Info rather than warning because store-downloaded effects on app-authored drafts are legitimate; only CLI-written stale slugs are at risk.
 - `export-srt <project> [--granularity line|word] [--format srt|vtt]` — word-level caption export. Captions created by `caption --karaoke` carry real per-word timing and export it exactly; plain captions interpolate word timing proportionally by word length (stated in `--help`). SRT + word emits one cue per word; VTT + word emits one cue per phrase with inline `<hh:mm:ss.mmm>` karaoke timestamps for burn-in pipelines. Defaults (`line`, `srt`) reproduce the previous output byte-identically.
 - `keyframe ... --easing <linear|ease-in|ease-out|ease-in-out>` — CapCut-native easing curves, also accepted per-line (`easing` key) in `keyframe --batch` JSONL and in the `compile` spec's keyframe op. The app does not store named curve types: the UI writes `FreeCurveInOut` bezier control handles on both keyframes of the eased segment, and the emitted encodings are locked against a UI-oracle capture (prior art: capcut-cli-david). The `ken-burns` skill default changed linear → ease-out to match what the CapCut UI itself produces.
 - `detect-scenes <video> [--threshold <0..1>] [--min-gap <s>] [--limit <n>] [--json]` — deterministic ffmpeg scene-cut detection (no AI, zero new dependencies) to seed the long-form → shorts flow: prints detected cut points (seconds, `hh:mm:ss.mmm` timecode, scene score) plus a ready-to-use contiguous segment list in seconds and draft-native microseconds. Follows the `probe`/`render` external-binary pattern, including a clear actionable error when ffmpeg is missing.
-- `make-preset <project> <text-segment-id> --out <preset.json>` — extract a hand-tuned text style (font, colors, style flags, alignment/transform, bubble, karaoke/multi-style ranges) from an existing draft into a versioned, portable preset file; apply it with the new `--preset <file>` flag on `add-text`, `text-style`, and `caption`. Explicit CLI flags override preset values. Addresses the recurring ecosystem ask for programmatic font/style reuse (GuanYixuan/pyJianYingDraft#192, Hommy-master/capcut-mate#57).
+- `make-preset <project> <text-segment-id> --out <preset.json>` — extract a hand-tuned text style (font, colors, style flags, alignment/transform, bubble, karaoke/multi-style ranges) from an existing draft into a versioned, portable preset file; apply it with the new `--preset <file>` flag on `add-text`, `text-style`, and `caption`. Addresses the recurring ecosystem ask for programmatic font/style reuse (GuanYixuan/pyJianYingDraft#192, Hommy-master/capcut-mate#57). Contract:
+  - **Explicit flags beat the preset — including its ranges.** `--color` / `--font-size` override every captured `text_ranges` block over the covered span, not just the base style, so a karaoke/highlight preset re-renders in the flag color/size; applying the same preset without those flags preserves the per-range styling.
+  - **Presets are schema-validated on load.** `transform` must be an object with finite numeric `x`/`y`, `bubble` must carry non-empty `effect_id`/`resource_id`, `text_ranges` must be an array of objects with integer `start`/`end` where `end > start` and correctly typed style fields. A malformed preset is rejected with a clear error and is never written into the draft.
+  - **Rangeless preset onto a multi-range segment collapses the ranges.** Applying a preset that carries no `text_ranges` onto a segment that still holds multiple range blocks (leftover karaoke/highlight) collapses them to the single uniform preset style spanning the whole text — consistent with the "applies the full preset" contract. A preset that itself carries ranges applies them unchanged. Documented in `--help`.
+  - **`make-preset --dry-run` writes nothing** — the `--out` file is neither created nor overwritten, and the JSON output reports `dryRun:true` with `written:false` (a normal run reports `written:true`).
+- Parser: the value-consuming flags introduced in this release (`--threshold`, `--min-gap`, `--limit`, `--json`, `--granularity`, `--format`, `--easing`, `--preset`, `--apply`) are scoped to the commands that declare them instead of being consumed globally, so free-text positionals that contain a flag-like substring survive verbatim (e.g. `add-text ... New Year --limit 5 drinks` stores the literal text). Flags that earlier releases already parsed globally are unchanged.
 
 ### Documentation
 
diff --git a/docs/command-reference.json b/docs/command-reference.json
index d29ddf3..f76f18e 100644
--- a/docs/command-reference.json
+++ b/docs/command-reference.json
@@ -1045,7 +1045,7 @@
           ],
           "type": "enum",
           "required": false,
-          "description": "Interpolation easing to adjacent keyframes.",
+          "description": "Interpolation easing to adjacent keyframes. Needs an adjacent keyframe on the same property; a lone eased keyframe stays linear (warns).",
           "values": [
             "linear",
             "ease-in",
@@ -3746,11 +3746,11 @@
     },
     {
       "name": "sync-timelines",
-      "summary": "Reconcile timeline mirrors (template-2.tmp, draft_info.json) drifted from draft_content.json (plan by default; --apply writes).",
-      "usage": "capcut sync-timelines <project> [--apply]",
+      "summary": "Reconcile drifted timeline mirrors (template-2.tmp, draft_info.json) from a read-only draft_content.json (plan with mtimes by default; --apply rewrites only the drifted mirrors).",
+      "usage": "capcut sync-timelines <project-dir> [--apply]",
       "positionals": [
         {
-          "name": "project",
+          "name": "project-dir",
           "type": "path",
           "required": true
         }
@@ -3763,7 +3763,7 @@
           ],
           "type": "boolean",
           "required": false,
-          "description": "Write the reconciled timelines (default: print the plan only)."
+          "description": "Rewrite only the drifted mirror files from draft_content.json (default: print the plan only)."
         }
       ],
       "mutates": true,
@@ -4328,6 +4328,15 @@
           "required": false,
           "description": "FFmpeg binary."
         },
+        {
+          "name": "ffprobe_cmd",
+          "flags": [
+            "--ffprobe-cmd"
+          ],
+          "type": "path",
+          "required": false,
+          "description": "ffprobe binary for the video-stream duration (falls back to the container duration without it)."
+        },
         {
           "name": "json",
           "flags": [
@@ -4340,7 +4349,8 @@
       ],
       "mutates": false,
       "prerequisites": [
-        "ffmpeg"
+        "ffmpeg",
+        "ffprobe (optional)"
       ],
       "output": {
         "type": "object",
diff --git a/docs/command-reference.md b/docs/command-reference.md
index 7484b9d..aafda68 100644
--- a/docs/command-reference.md
+++ b/docs/command-reference.md
@@ -66,7 +66,7 @@
 | `doctor` | `capcut doctor` | no | Environment preflight (Node, whisper, API key, project dir). |
 | `diagnose` | `capcut diagnose <project> [--bundle <report.json>]` | no | Inspect canonical draft files, divergence, and editor-write safety. |
 | `fixture` | `capcut fixture <project> --out <dir>` | no | Build a shareable, redacted compatibility bundle (timeline JSON only) for a version-support issue. |
-| `sync-timelines` | `capcut sync-timelines <project> [--apply]` | yes | Reconcile timeline mirrors (template-2.tmp, draft_info.json) drifted from draft_content.json (plan by default; --apply writes). |
+| `sync-timelines` | `capcut sync-timelines <project-dir> [--apply]` | yes | Reconcile drifted timeline mirrors (template-2.tmp, draft_info.json) from a read-only draft_content.json (plan with mtimes by default; --apply rewrites only the drifted mirrors). |
 | `restore` | `capcut restore <project> [--step <number> \| --list]` | yes | Undo writes from .bak / snapshot history (--step N, --list). |
 | `serve` | `capcut serve [--queue <path>] [options]` | no | Run a stateless JSONL job queue from stdin/--queue. |
 | `decrypt` | `capcut decrypt <project-or-file>` | no | Detect JianYing 6.0+ encryption and explain the workaround. |