clipwise 0.9.1 → 0.10.1

package/dist/cli/index.js

@@ -293,7 +293,9 @@ var init_types = __esm({
       /** Fade-in duration in milliseconds. */
       fadeIn: z.number().min(0).default(0),
       /** Fade-out duration in milliseconds. */
-      fadeOut: z.number().min(0).default(0)
+      fadeOut: z.number().min(0).default(0),
+      /** 트랙 BPM — scenes 타임라인에서 지정 시 신 길이를 비트 격자에 스냅(비트 싱크 컷). */
+      bpm: z.number().min(40).max(220).optional()
     });
     AuthConfigSchema = z.object({
       /** Path to a Playwright storageState JSON file (cookies + localStorage). */
@@ -324,6 +326,8 @@ var init_types = __esm({
     PrepareConfigSchema = z.object({
       /** 녹화에서 숨길 요소의 CSS 셀렉터 (쿠키 배너, dev 오버레이 등). */
       hide: z.array(z.string().min(1)).default([]),
+      /** 블러 처리할 요소의 CSS 셀렉터 (이메일, 금액 등 민감 정보) — 스크롤·이동을 따라간다. */
+      mask: z.array(z.string().min(1)).default([]),
       /** Date/Date.now를 이 시각으로 고정 (ISO 8601, 예: "2026-06-10T09:00:00Z"). */
       freezeTime: z.string().optional(),
       /** Math.random을 이 시드의 결정론적 PRNG로 대체. */
@@ -357,7 +361,7 @@ var init_types = __esm({
       steps: z.array(StepSchema).min(1)
     });
     SceneFxSchema = z.object({
-      kind: z.enum(["circle", "arrow"]),
+      kind: z.enum(["circle", "arrow", "spotlight"]),
       /** 대상 요소 셀렉터 — bounding box를 실측해 좌표로 사용. */
       selector: z.string().optional(),
       /** 명시 좌표 — circle: [x,y,w,h], arrow: [x1,y1,x2,y2]. */
@@ -387,8 +391,14 @@ var init_types = __esm({
         /** 크롭 높이 상한 (px, 원본 기준) — 와이드 스트립 연출용. */
         maxH: z.number().optional()
       }).optional(),
-      /** 푸시인 카메라 (스케일 from→to). */
-      push: z.object({ from: z.number().default(1), to: z.number().default(1) }).optional(),
+      /** 푸시인 카메라 (스케일 from→to).
+       *  origin: 푸시 중심점 — 셀렉터(실측) 지정 시 그 요소를 향해 밀어 들어가
+       *  다음 신의 크롭과 이어지는 매치컷을 만든다. 기본은 화면 중앙 약간 위. */
+      push: z.object({
+        from: z.number().default(1),
+        to: z.number().default(1),
+        origin: z.string().optional()
+      }).optional(),
       /** 푸티지 인용 시작점 — 초(number) 또는 step 경계 anchor. */
       start: z.union([z.number(), z.object({ step: z.number().int().min(0), offset: z.number().default(0) })]).default(0),
       /** 푸티지 재생 배속. */
@@ -571,6 +581,12 @@ function buildHideCss(selectors) {
   visibility: hidden !important;
 }`;
 }
+function buildMaskCss(selectors) {
+  return `${selectors.join(",\n")} {
+  filter: blur(10px) !important;
+  border-radius: 4px;
+}`;
+}
 function buildCssInjectionScript(css) {
   return `(() => {
   const apply = () => {
@@ -648,6 +664,9 @@ async function applyPrepare(context, prepare) {
   if (prepare.hide.length > 0) {
     cssChunks.push(buildHideCss(prepare.hide));
   }
+  if (prepare.mask.length > 0) {
+    cssChunks.push(buildMaskCss(prepare.mask));
+  }
   if (prepare.inject?.css) {
     const cssFiles = Array.isArray(prepare.inject.css) ? prepare.inject.css : [prepare.inject.css];
     for (const file of cssFiles) {
@@ -3959,6 +3978,7 @@ __export(runner_exports, {
 });
 import { chromium as chromium2 } from "playwright";
 import { createServer } from "http";
+import { createHash } from "crypto";
 import { execSync } from "child_process";
 import { readFile as readFile4, writeFile as writeFile2, mkdtemp, rm as rm2 } from "fs/promises";
 import { existsSync as existsSync2 } from "fs";
@@ -4100,21 +4120,21 @@ async function recordFootageTake(scenario, scene, selectors) {
   const recorder = new ClipwiseRecorder();
   const session = await recorder.record(takeScenario);
   const renderer = new CanvasRenderer(takeScenario.effects, segmentOutput(scenario), scene.steps);
-  const composed = [];
-  for await (const f of renderer.composeStream(session.frames)) composed.push(f);
-  const frames = await Promise.all(
-    composed.map(
-      (f) => f.rawInfo ? sharp10(f.buffer, {
-        raw: { width: f.rawInfo.width, height: f.rawInfo.height, channels: f.rawInfo.channels }
-      }).png().toBuffer() : Promise.resolve(f.buffer)
-    )
-  );
+  const framesDir = await mkdtemp(join2(tmpdir2(), `clipwise-footage-${scene.id}-`));
+  let count = 0;
+  for await (const f of renderer.composeStream(session.frames)) {
+    const png = f.rawInfo ? await sharp10(f.buffer, {
+      raw: { width: f.rawInfo.width, height: f.rawInfo.height, channels: f.rawInfo.channels }
+    }).png().toBuffer() : f.buffer;
+    await writeFile2(join2(framesDir, `${count}.png`), png);
+    count++;
+  }
   const anchors = [];
   for (let k = 0; k < scene.steps.length; k++) {
     const idx = session.frames.findIndex((f) => (f.stepIndex ?? 0) >= k);
     anchors.push(Math.max(0, idx) / scenario.output.fps);
   }
-  return { frames, anchors, boxes };
+  return { framesDir, count, anchors, boxes };
 }
 function fitCardW(cw, ch, maxW = 940, maxH = 540) {
   return Math.round(Math.min(maxW, maxH * cw / ch));
@@ -4144,7 +4164,7 @@ async function captureMotionSegment(templateUrl, props, durationMs, scenario) {
   await browser.close();
   return { buffer: await encodeMp4(frames, segmentOutput(scenario)), seconds: totalFrames / fps };
 }
-function vignetteProps(scene, take, serverBase, scenario, brand) {
+function vignetteProps(scene, take, serverBase, scenario, brand, durMs) {
   const W = scenario.viewport.width;
   const H = scenario.viewport.height;
   let crop = { x: 0, y: 0, w: W, h: H };
@@ -4168,13 +4188,13 @@ function vignetteProps(scene, take, serverBase, scenario, brand) {
   const props = {
     accent: brand.accent,
     font: brand.font,
-    dur: scene.duration / 1e3,
+    dur: durMs / 1e3,
     layout: scene.layout,
     num: scene.num ?? "",
     label: scene.label ?? "",
     caption: scene.caption ?? "",
     base: serverBase,
-    count: take.frames.length,
+    count: take.count,
     fps: scenario.output.fps,
     start,
     rate: scene.rate,
@@ -4187,13 +4207,19 @@ function vignetteProps(scene, take, serverBase, scenario, brand) {
     pushTo: scene.push?.to ?? 1
   };
   if (scene.code?.length) props.code = scene.code.join("||");
+  if (scene.push?.origin) {
+    const box = take.boxes.get(scene.push.origin);
+    if (!box) throw new Error(`vignette push.origin selector "${scene.push.origin}" not found in footage "${scene.footage}"`);
+    props.pushOx = Math.max(0, Math.min(100, (box.x + box.width / 2 - crop.x) / crop.w * 100)).toFixed(1);
+    props.pushOy = Math.max(0, Math.min(100, (box.y + box.height / 2 - crop.y) / crop.h * 100)).toFixed(1);
+  }
   if (brand.annotations && scene.fx.length > 0) {
     props.fx = scene.fx.map((fx) => {
       let coords = fx.coords;
       if (fx.selector) {
         const box = take.boxes.get(fx.selector);
         if (!box) throw new Error(`vignette fx selector "${fx.selector}" not found in footage "${scene.footage}"`);
-        coords = fx.kind === "circle" ? [box.x, box.y, box.width, box.height] : [box.x - 160, box.y + 120, box.x - 12, box.y + box.height / 2];
+        coords = fx.kind === "arrow" ? [box.x - 160, box.y + 120, box.x - 12, box.y + box.height / 2] : [box.x, box.y, box.width, box.height];
       }
       return `${fx.kind}@${coords.join(",")}@${fx.delay}`;
     }).join(";");
@@ -4210,6 +4236,7 @@ async function renderScenesTimeline(scenario, scenarioDir, onProgress) {
     if (scene.type !== "vignette") continue;
     const set = selectorsByFootage.get(scene.footage) ?? /* @__PURE__ */ new Set();
     if (scene.crop?.selector) set.add(scene.crop.selector);
+    if (scene.push?.origin) set.add(scene.push.origin);
     for (const fx of scene.fx) if (fx.selector) set.add(fx.selector);
     selectorsByFootage.set(scene.footage, set);
   }
@@ -4225,9 +4252,14 @@ async function renderScenesTimeline(scenario, scenarioDir, onProgress) {
     const m = req.url?.match(/^\/([\w-]+)\/(\d+)\.png$/);
     const take = m ? takes.get(m[1]) : void 0;
     if (take) {
-      const idx = Math.min(take.frames.length - 1, parseInt(m[2], 10));
-      res.writeHead(200, { "content-type": "image/png", "cache-control": "max-age=3600" });
-      res.end(take.frames[idx]);
+      const idx = Math.min(take.count - 1, parseInt(m[2], 10));
+      readFile4(join2(take.framesDir, `${idx}.png`)).then((png) => {
+        res.writeHead(200, { "content-type": "image/png", "cache-control": "max-age=3600" });
+        res.end(png);
+      }).catch(() => {
+        res.writeHead(404);
+        res.end();
+      });
     } else {
       res.writeHead(404);
       res.end();
@@ -4235,27 +4267,32 @@ async function renderScenesTimeline(scenario, scenarioDir, onProgress) {
   });
   await new Promise((r) => server.listen(0, r));
   const port = server.address().port;
-  const totalMs = timeline.reduce((s, sc) => s + sc.duration, 0);
+  const beatMs = scenario.audio?.bpm ? 6e4 / scenario.audio.bpm : 0;
+  const durations = timeline.map(
+    (sc) => beatMs ? Math.max(beatMs, Math.round(sc.duration / beatMs) * beatMs) : sc.duration
+  );
+  const totalMs = durations.reduce((s, d) => s + d, 0);
   let elapsedMs = 0;
   const segments = [];
   const tmp = await mkdtemp(join2(tmpdir2(), "clipwise-scenes-"));
   try {
     for (let i = 0; i < timeline.length; i++) {
       const scene = timeline[i];
+      const dur = durations[i];
       const label = scene.type === "motion" ? scene.template : `vignette(${scene.footage})`;
       onProgress?.({ scene: i + 1, total: timeline.length, label });
       const thread = brand.annotations ? {
         threadFrom: (elapsedMs / totalMs).toFixed(4),
-        threadTo: ((elapsedMs + scene.duration) / totalMs).toFixed(4)
+        threadTo: ((elapsedMs + dur) / totalMs).toFixed(4)
       } : {};
-      elapsedMs += scene.duration;
+      elapsedMs += dur;
       let segment;
       if (scene.type === "motion") {
         const url = resolveMotionTemplate(scene.template, scenarioDir);
         segment = await captureMotionSegment(
           url,
-          { accent: brand.accent, font: brand.font, dur: scene.duration / 1e3, ...scene.props, ...thread },
-          scene.duration,
+          { accent: brand.accent, font: brand.font, dur: dur / 1e3, ...scene.props, ...thread },
+          dur,
           scenario
         );
       } else {
@@ -4263,8 +4300,8 @@ async function renderScenesTimeline(scenario, scenarioDir, onProgress) {
         const url = resolveMotionTemplate("vignette", scenarioDir);
         segment = await captureMotionSegment(
           url,
-          { ...vignetteProps(scene, take, `http://localhost:${port}/${scene.footage}`, scenario, brand), ...thread },
-          scene.duration,
+          { ...vignetteProps(scene, take, `http://localhost:${port}/${scene.footage}`, scenario, brand, dur), ...thread },
+          dur,
           scenario
         );
       }
@@ -4278,13 +4315,39 @@ async function renderScenesTimeline(scenario, scenarioDir, onProgress) {
   const filters = segments.map((_, i) => `[${i}:v]format=yuv420p[v${i}]`).join(";");
   const concatInputs = segments.map((_, i) => `[v${i}]`).join("");
   const outPath = join2(tmp, "timeline.mp4");
+  let audioInput = "";
+  let audioMap = "";
+  const totalSec = totalMs / 1e3;
+  if (scenario.audio) {
+    const a = scenario.audio;
+    let audioPath;
+    if (/^https?:\/\//.test(a.file)) {
+      const hash = createHash("sha256").update(a.file).digest("hex").slice(0, 16);
+      audioPath = join2(tmpdir2(), `clipwise-audio-${hash}${a.file.match(/\.\w{2,4}$/)?.[0] ?? ".mp3"}`);
+      if (!existsSync2(audioPath)) {
+        execSync(`curl -sL -o "${audioPath}" "${a.file}"`, { stdio: ["ignore", "ignore", "pipe"] });
+      }
+    } else {
+      audioPath = isAbsolute2(a.file) ? a.file : resolve2(scenarioDir, a.file);
+    }
+    const af = [];
+    if (a.volume !== 1) af.push(`volume=${a.volume}`);
+    if (a.fadeIn > 0) af.push(`afade=t=in:d=${a.fadeIn / 1e3}`);
+    if (a.fadeOut > 0) af.push(`afade=t=out:st=${Math.max(0, totalSec - a.fadeOut / 1e3)}:d=${a.fadeOut / 1e3}`);
+    audioInput = `-stream_loop -1 -i "${audioPath}" `;
+    audioMap = `-map ${segments.length}:a ${af.length ? `-af "${af.join(",")}" ` : ""}-c:a aac -b:a 192k `;
+  }
   execSync(
-    `ffmpeg -y ${segments.map((s) => `-i "${s.path}"`).join(" ")} -filter_complex "${filters};${concatInputs}concat=n=${segments.length}:v=1:a=0[v]" -map "[v]" -c:v libx264 -crf 16 -preset slow -movflags +faststart "${outPath}"`,
+    `ffmpeg -y ${segments.map((s) => `-i "${s.path}"`).join(" ")} ${audioInput}-filter_complex "${filters};${concatInputs}concat=n=${segments.length}:v=1:a=0[v]" -map "[v]" ${audioMap}-t ${totalSec.toFixed(3)} -c:v libx264 -crf 16 -preset slow -movflags +faststart "${outPath}"`,
     { stdio: ["ignore", "ignore", "pipe"] }
   );
   const buffer = await readFile4(outPath);
   await rm2(tmp, { recursive: true, force: true }).catch(() => {
   });
+  for (const take of takes.values()) {
+    await rm2(take.framesDir, { recursive: true, force: true }).catch(() => {
+    });
+  }
   return buffer;
 }
 var init_runner = __esm({
@@ -4522,7 +4585,7 @@ import { homedir } from "os";
 var program = new Command();
 program.name("clipwise").description(
   "Playwright-based cinematic screen recorder for product demos"
-).version("0.9.1");
+).version("0.10.1");
 program.command("record").description("Record a demo from a YAML scenario file").argument("<scenario>", "Path to YAML scenario file").option("-o, --output <dir>", "Output directory (default: scenario outputDir or .clipwise/output)").option(
   "-f, --format <format>",
   "Output format (gif|mp4|png-sequence)"

package/dist/index.d.ts

@@ -1934,16 +1934,20 @@ declare const AudioConfigSchema: z.ZodObject<{
     fadeIn: z.ZodDefault<z.ZodNumber>;
     /** Fade-out duration in milliseconds. */
     fadeOut: z.ZodDefault<z.ZodNumber>;
+    /** 트랙 BPM — scenes 타임라인에서 지정 시 신 길이를 비트 격자에 스냅(비트 싱크 컷). */
+    bpm: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     file: string;
     volume: number;
     fadeIn: number;
     fadeOut: number;
+    bpm?: number | undefined;
 }, {
     file: string;
     volume?: number | undefined;
     fadeIn?: number | undefined;
     fadeOut?: number | undefined;
+    bpm?: number | undefined;
 }>;
 type AudioConfig = z.infer<typeof AudioConfigSchema>;
 /**
@@ -2045,6 +2049,8 @@ type MockRoute = z.infer<typeof MockRouteSchema>;
 declare const PrepareConfigSchema: z.ZodObject<{
     /** 녹화에서 숨길 요소의 CSS 셀렉터 (쿠키 배너, dev 오버레이 등). */
     hide: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** 블러 처리할 요소의 CSS 셀렉터 (이메일, 금액 등 민감 정보) — 스크롤·이동을 따라간다. */
+    mask: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     /** Date/Date.now를 이 시각으로 고정 (ISO 8601, 예: "2026-06-10T09:00:00Z"). */
     freezeTime: z.ZodOptional<z.ZodString>;
     /** Math.random을 이 시드의 결정론적 PRNG로 대체. */
@@ -2096,6 +2102,7 @@ declare const PrepareConfigSchema: z.ZodObject<{
     }>>;
 }, "strip", z.ZodTypeAny, {
     hide: string[];
+    mask: string[];
     mock: {
         status: number;
         url: string;
@@ -2115,6 +2122,7 @@ declare const PrepareConfigSchema: z.ZodObject<{
     } | undefined;
 }, {
     hide?: string[] | undefined;
+    mask?: string[] | undefined;
     freezeTime?: string | undefined;
     seedRandom?: number | undefined;
     storage?: {
@@ -3374,9 +3382,10 @@ declare const ScreenSceneSchema: z.ZodObject<{
         } | undefined;
     }[];
 }>;
-/** 선 드로잉 주석 — 좌표는 셀렉터 실측(권장) 또는 푸티지 원본 px. */
+/** 푸티지 주석 — circle/arrow(선 드로잉), spotlight(주변 디밍).
+ *  좌표는 셀렉터 실측(권장) 또는 푸티지 원본 px. */
 declare const SceneFxSchema: z.ZodObject<{
-    kind: z.ZodEnum<["circle", "arrow"]>;
+    kind: z.ZodEnum<["circle", "arrow", "spotlight"]>;
     /** 대상 요소 셀렉터 — bounding box를 실측해 좌표로 사용. */
     selector: z.ZodOptional<z.ZodString>;
     /** 명시 좌표 — circle: [x,y,w,h], arrow: [x1,y1,x2,y2]. */
@@ -3385,11 +3394,11 @@ declare const SceneFxSchema: z.ZodObject<{
     delay: z.ZodDefault<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     delay: number;
-    kind: "circle" | "arrow";
+    kind: "circle" | "arrow" | "spotlight";
     selector?: string | undefined;
     coords?: number[] | undefined;
 }, {
-    kind: "circle" | "arrow";
+    kind: "circle" | "arrow" | "spotlight";
     selector?: string | undefined;
     delay?: number | undefined;
     coords?: number[] | undefined;
@@ -3433,16 +3442,21 @@ declare const VignetteSceneSchema: z.ZodObject<{
         h?: number | undefined;
         maxH?: number | undefined;
     }>>;
-    /** 푸시인 카메라 (스케일 from→to). */
+    /** 푸시인 카메라 (스케일 from→to).
+     *  origin: 푸시 중심점 — 셀렉터(실측) 지정 시 그 요소를 향해 밀어 들어가
+     *  다음 신의 크롭과 이어지는 매치컷을 만든다. 기본은 화면 중앙 약간 위. */
     push: z.ZodOptional<z.ZodObject<{
         from: z.ZodDefault<z.ZodNumber>;
         to: z.ZodDefault<z.ZodNumber>;
+        origin: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         from: number;
         to: number;
+        origin?: string | undefined;
     }, {
         from?: number | undefined;
         to?: number | undefined;
+        origin?: string | undefined;
     }>>;
     /** 푸티지 인용 시작점 — 초(number) 또는 step 경계 anchor. */
     start: z.ZodDefault<z.ZodUnion<[z.ZodNumber, z.ZodObject<{
@@ -3458,7 +3472,7 @@ declare const VignetteSceneSchema: z.ZodObject<{
     /** 푸티지 재생 배속. */
     rate: z.ZodDefault<z.ZodNumber>;
     fx: z.ZodDefault<z.ZodArray<z.ZodObject<{
-        kind: z.ZodEnum<["circle", "arrow"]>;
+        kind: z.ZodEnum<["circle", "arrow", "spotlight"]>;
         /** 대상 요소 셀렉터 — bounding box를 실측해 좌표로 사용. */
         selector: z.ZodOptional<z.ZodString>;
         /** 명시 좌표 — circle: [x,y,w,h], arrow: [x1,y1,x2,y2]. */
@@ -3467,11 +3481,11 @@ declare const VignetteSceneSchema: z.ZodObject<{
         delay: z.ZodDefault<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
         delay: number;
-        kind: "circle" | "arrow";
+        kind: "circle" | "arrow" | "spotlight";
         selector?: string | undefined;
         coords?: number[] | undefined;
     }, {
-        kind: "circle" | "arrow";
+        kind: "circle" | "arrow" | "spotlight";
         selector?: string | undefined;
         delay?: number | undefined;
         coords?: number[] | undefined;
@@ -3488,13 +3502,14 @@ declare const VignetteSceneSchema: z.ZodObject<{
     rate: number;
     fx: {
         delay: number;
-        kind: "circle" | "arrow";
+        kind: "circle" | "arrow" | "spotlight";
         selector?: string | undefined;
         coords?: number[] | undefined;
     }[];
     push?: {
         from: number;
         to: number;
+        origin?: string | undefined;
     } | undefined;
     code?: string[] | undefined;
     crop?: {
@@ -3516,6 +3531,7 @@ declare const VignetteSceneSchema: z.ZodObject<{
     push?: {
         from?: number | undefined;
         to?: number | undefined;
+        origin?: string | undefined;
     } | undefined;
     code?: string[] | undefined;
     crop?: {
@@ -3537,7 +3553,7 @@ declare const VignetteSceneSchema: z.ZodObject<{
     } | undefined;
     rate?: number | undefined;
     fx?: {
-        kind: "circle" | "arrow";
+        kind: "circle" | "arrow" | "spotlight";
         selector?: string | undefined;
         delay?: number | undefined;
         coords?: number[] | undefined;
@@ -4817,16 +4833,21 @@ declare const SceneSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
         h?: number | undefined;
         maxH?: number | undefined;
     }>>;
-    /** 푸시인 카메라 (스케일 from→to). */
+    /** 푸시인 카메라 (스케일 from→to).
+     *  origin: 푸시 중심점 — 셀렉터(실측) 지정 시 그 요소를 향해 밀어 들어가
+     *  다음 신의 크롭과 이어지는 매치컷을 만든다. 기본은 화면 중앙 약간 위. */
     push: z.ZodOptional<z.ZodObject<{
         from: z.ZodDefault<z.ZodNumber>;
         to: z.ZodDefault<z.ZodNumber>;
+        origin: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         from: number;
         to: number;
+        origin?: string | undefined;
     }, {
         from?: number | undefined;
         to?: number | undefined;
+        origin?: string | undefined;
     }>>;
     /** 푸티지 인용 시작점 — 초(number) 또는 step 경계 anchor. */
     start: z.ZodDefault<z.ZodUnion<[z.ZodNumber, z.ZodObject<{
@@ -4842,7 +4863,7 @@ declare const SceneSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     /** 푸티지 재생 배속. */
     rate: z.ZodDefault<z.ZodNumber>;
     fx: z.ZodDefault<z.ZodArray<z.ZodObject<{
-        kind: z.ZodEnum<["circle", "arrow"]>;
+        kind: z.ZodEnum<["circle", "arrow", "spotlight"]>;
         /** 대상 요소 셀렉터 — bounding box를 실측해 좌표로 사용. */
         selector: z.ZodOptional<z.ZodString>;
         /** 명시 좌표 — circle: [x,y,w,h], arrow: [x1,y1,x2,y2]. */
@@ -4851,11 +4872,11 @@ declare const SceneSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
         delay: z.ZodDefault<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
         delay: number;
-        kind: "circle" | "arrow";
+        kind: "circle" | "arrow" | "spotlight";
         selector?: string | undefined;
         coords?: number[] | undefined;
     }, {
-        kind: "circle" | "arrow";
+        kind: "circle" | "arrow" | "spotlight";
         selector?: string | undefined;
         delay?: number | undefined;
         coords?: number[] | undefined;
@@ -4872,13 +4893,14 @@ declare const SceneSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     rate: number;
     fx: {
         delay: number;
-        kind: "circle" | "arrow";
+        kind: "circle" | "arrow" | "spotlight";
         selector?: string | undefined;
         coords?: number[] | undefined;
     }[];
     push?: {
         from: number;
         to: number;
+        origin?: string | undefined;
     } | undefined;
     code?: string[] | undefined;
     crop?: {
@@ -4900,6 +4922,7 @@ declare const SceneSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     push?: {
         from?: number | undefined;
         to?: number | undefined;
+        origin?: string | undefined;
     } | undefined;
     code?: string[] | undefined;
     crop?: {
@@ -4921,7 +4944,7 @@ declare const SceneSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     } | undefined;
     rate?: number | undefined;
     fx?: {
-        kind: "circle" | "arrow";
+        kind: "circle" | "arrow" | "spotlight";
         selector?: string | undefined;
         delay?: number | undefined;
         coords?: number[] | undefined;
@@ -5006,6 +5029,8 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
     prepare: z.ZodOptional<z.ZodObject<{
         /** 녹화에서 숨길 요소의 CSS 셀렉터 (쿠키 배너, dev 오버레이 등). */
         hide: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        /** 블러 처리할 요소의 CSS 셀렉터 (이메일, 금액 등 민감 정보) — 스크롤·이동을 따라간다. */
+        mask: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
         /** Date/Date.now를 이 시각으로 고정 (ISO 8601, 예: "2026-06-10T09:00:00Z"). */
         freezeTime: z.ZodOptional<z.ZodString>;
         /** Math.random을 이 시드의 결정론적 PRNG로 대체. */
@@ -5057,6 +5082,7 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         }>>;
     }, "strip", z.ZodTypeAny, {
         hide: string[];
+        mask: string[];
         mock: {
             status: number;
             url: string;
@@ -5076,6 +5102,7 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         } | undefined;
     }, {
         hide?: string[] | undefined;
+        mask?: string[] | undefined;
         freezeTime?: string | undefined;
         seedRandom?: number | undefined;
         storage?: {
@@ -5525,16 +5552,20 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         fadeIn: z.ZodDefault<z.ZodNumber>;
         /** Fade-out duration in milliseconds. */
         fadeOut: z.ZodDefault<z.ZodNumber>;
+        /** 트랙 BPM — scenes 타임라인에서 지정 시 신 길이를 비트 격자에 스냅(비트 싱크 컷). */
+        bpm: z.ZodOptional<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
         file: string;
         volume: number;
         fadeIn: number;
         fadeOut: number;
+        bpm?: number | undefined;
     }, {
         file: string;
         volume?: number | undefined;
         fadeIn?: number | undefined;
         fadeOut?: number | undefined;
+        bpm?: number | undefined;
     }>>;
     /** steps 기반(클래식) 시나리오. scenes가 있으면 생략 가능. */
     steps: z.ZodDefault<z.ZodArray<z.ZodObject<{
@@ -7712,16 +7743,21 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
             h?: number | undefined;
             maxH?: number | undefined;
         }>>;
-        /** 푸시인 카메라 (스케일 from→to). */
+        /** 푸시인 카메라 (스케일 from→to).
+         *  origin: 푸시 중심점 — 셀렉터(실측) 지정 시 그 요소를 향해 밀어 들어가
+         *  다음 신의 크롭과 이어지는 매치컷을 만든다. 기본은 화면 중앙 약간 위. */
         push: z.ZodOptional<z.ZodObject<{
             from: z.ZodDefault<z.ZodNumber>;
             to: z.ZodDefault<z.ZodNumber>;
+            origin: z.ZodOptional<z.ZodString>;
         }, "strip", z.ZodTypeAny, {
             from: number;
             to: number;
+            origin?: string | undefined;
         }, {
             from?: number | undefined;
             to?: number | undefined;
+            origin?: string | undefined;
         }>>;
         /** 푸티지 인용 시작점 — 초(number) 또는 step 경계 anchor. */
         start: z.ZodDefault<z.ZodUnion<[z.ZodNumber, z.ZodObject<{
@@ -7737,7 +7773,7 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         /** 푸티지 재생 배속. */
         rate: z.ZodDefault<z.ZodNumber>;
         fx: z.ZodDefault<z.ZodArray<z.ZodObject<{
-            kind: z.ZodEnum<["circle", "arrow"]>;
+            kind: z.ZodEnum<["circle", "arrow", "spotlight"]>;
             /** 대상 요소 셀렉터 — bounding box를 실측해 좌표로 사용. */
             selector: z.ZodOptional<z.ZodString>;
             /** 명시 좌표 — circle: [x,y,w,h], arrow: [x1,y1,x2,y2]. */
@@ -7746,11 +7782,11 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
             delay: z.ZodDefault<z.ZodNumber>;
         }, "strip", z.ZodTypeAny, {
             delay: number;
-            kind: "circle" | "arrow";
+            kind: "circle" | "arrow" | "spotlight";
             selector?: string | undefined;
             coords?: number[] | undefined;
         }, {
-            kind: "circle" | "arrow";
+            kind: "circle" | "arrow" | "spotlight";
             selector?: string | undefined;
             delay?: number | undefined;
             coords?: number[] | undefined;
@@ -7767,13 +7803,14 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         rate: number;
         fx: {
             delay: number;
-            kind: "circle" | "arrow";
+            kind: "circle" | "arrow" | "spotlight";
             selector?: string | undefined;
             coords?: number[] | undefined;
         }[];
         push?: {
             from: number;
             to: number;
+            origin?: string | undefined;
         } | undefined;
         code?: string[] | undefined;
         crop?: {
@@ -7795,6 +7832,7 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         push?: {
             from?: number | undefined;
             to?: number | undefined;
+            origin?: string | undefined;
         } | undefined;
         code?: string[] | undefined;
         crop?: {
@@ -7816,7 +7854,7 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         } | undefined;
         rate?: number | undefined;
         fx?: {
-            kind: "circle" | "arrow";
+            kind: "circle" | "arrow" | "spotlight";
             selector?: string | undefined;
             delay?: number | undefined;
             coords?: number[] | undefined;
@@ -8084,6 +8122,7 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
     } | undefined;
     prepare?: {
         hide: string[];
+        mask: string[];
         mock: {
             status: number;
             url: string;
@@ -8107,6 +8146,7 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         volume: number;
         fadeIn: number;
         fadeOut: number;
+        bpm?: number | undefined;
     } | undefined;
     scenes?: ({
         type: "motion";
@@ -8282,13 +8322,14 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         rate: number;
         fx: {
             delay: number;
-            kind: "circle" | "arrow";
+            kind: "circle" | "arrow" | "spotlight";
             selector?: string | undefined;
             coords?: number[] | undefined;
         }[];
         push?: {
             from: number;
             to: number;
+            origin?: string | undefined;
         } | undefined;
         code?: string[] | undefined;
         crop?: {
@@ -8555,6 +8596,7 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
     } | undefined;
     prepare?: {
         hide?: string[] | undefined;
+        mask?: string[] | undefined;
         freezeTime?: string | undefined;
         seedRandom?: number | undefined;
         storage?: {
@@ -8589,6 +8631,7 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         volume?: number | undefined;
         fadeIn?: number | undefined;
         fadeOut?: number | undefined;
+        bpm?: number | undefined;
     } | undefined;
     scenes?: ({
         type: "motion";
@@ -8759,6 +8802,7 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         push?: {
             from?: number | undefined;
             to?: number | undefined;
+            origin?: string | undefined;
         } | undefined;
         code?: string[] | undefined;
         crop?: {
@@ -8780,7 +8824,7 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         } | undefined;
         rate?: number | undefined;
         fx?: {
-            kind: "circle" | "arrow";
+            kind: "circle" | "arrow" | "spotlight";
             selector?: string | undefined;
             delay?: number | undefined;
             coords?: number[] | undefined;
@@ -9048,6 +9092,7 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
     } | undefined;
     prepare?: {
         hide: string[];
+        mask: string[];
         mock: {
             status: number;
             url: string;
@@ -9071,6 +9116,7 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         volume: number;
         fadeIn: number;
         fadeOut: number;
+        bpm?: number | undefined;
     } | undefined;
     scenes?: ({
         type: "motion";
@@ -9246,13 +9292,14 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         rate: number;
         fx: {
             delay: number;
-            kind: "circle" | "arrow";
+            kind: "circle" | "arrow" | "spotlight";
             selector?: string | undefined;
             coords?: number[] | undefined;
         }[];
         push?: {
             from: number;
             to: number;
+            origin?: string | undefined;
         } | undefined;
         code?: string[] | undefined;
         crop?: {
@@ -9519,6 +9566,7 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
     } | undefined;
     prepare?: {
         hide?: string[] | undefined;
+        mask?: string[] | undefined;
         freezeTime?: string | undefined;
         seedRandom?: number | undefined;
         storage?: {
@@ -9553,6 +9601,7 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         volume?: number | undefined;
         fadeIn?: number | undefined;
         fadeOut?: number | undefined;
+        bpm?: number | undefined;
     } | undefined;
     scenes?: ({
         type: "motion";
@@ -9723,6 +9772,7 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         push?: {
             from?: number | undefined;
             to?: number | undefined;
+            origin?: string | undefined;
         } | undefined;
         code?: string[] | undefined;
         crop?: {
@@ -9744,7 +9794,7 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         } | undefined;
         rate?: number | undefined;
         fx?: {
-            kind: "circle" | "arrow";
+            kind: "circle" | "arrow" | "spotlight";
             selector?: string | undefined;
             delay?: number | undefined;
             coords?: number[] | undefined;

package/dist/index.js

@@ -62,6 +62,12 @@ function buildHideCss(selectors) {
   visibility: hidden !important;
 }`;
 }
+function buildMaskCss(selectors) {
+  return `${selectors.join(",\n")} {
+  filter: blur(10px) !important;
+  border-radius: 4px;
+}`;
+}
 function buildCssInjectionScript(css) {
   return `(() => {
   const apply = () => {
@@ -139,6 +145,9 @@ async function applyPrepare(context, prepare) {
   if (prepare.hide.length > 0) {
     cssChunks.push(buildHideCss(prepare.hide));
   }
+  if (prepare.mask.length > 0) {
+    cssChunks.push(buildMaskCss(prepare.mask));
+  }
   if (prepare.inject?.css) {
     const cssFiles = Array.isArray(prepare.inject.css) ? prepare.inject.css : [prepare.inject.css];
     for (const file of cssFiles) {
@@ -3515,6 +3524,7 @@ var StreamingSession = class extends EventEmitter {
 // src/scenes/runner.ts
 import { chromium as chromium2 } from "playwright";
 import { createServer } from "http";
+import { createHash } from "crypto";
 import { execSync } from "child_process";
 import { readFile as readFile3, writeFile as writeFile2, mkdtemp, rm as rm2 } from "fs/promises";
 import { existsSync as existsSync2 } from "fs";
@@ -3656,21 +3666,21 @@ async function recordFootageTake(scenario, scene, selectors) {
   const recorder = new ClipwiseRecorder();
   const session = await recorder.record(takeScenario);
   const renderer = new CanvasRenderer(takeScenario.effects, segmentOutput(scenario), scene.steps);
-  const composed = [];
-  for await (const f of renderer.composeStream(session.frames)) composed.push(f);
-  const frames = await Promise.all(
-    composed.map(
-      (f) => f.rawInfo ? sharp10(f.buffer, {
-        raw: { width: f.rawInfo.width, height: f.rawInfo.height, channels: f.rawInfo.channels }
-      }).png().toBuffer() : Promise.resolve(f.buffer)
-    )
-  );
+  const framesDir = await mkdtemp(join2(tmpdir2(), `clipwise-footage-${scene.id}-`));
+  let count = 0;
+  for await (const f of renderer.composeStream(session.frames)) {
+    const png = f.rawInfo ? await sharp10(f.buffer, {
+      raw: { width: f.rawInfo.width, height: f.rawInfo.height, channels: f.rawInfo.channels }
+    }).png().toBuffer() : f.buffer;
+    await writeFile2(join2(framesDir, `${count}.png`), png);
+    count++;
+  }
   const anchors = [];
   for (let k = 0; k < scene.steps.length; k++) {
     const idx = session.frames.findIndex((f) => (f.stepIndex ?? 0) >= k);
     anchors.push(Math.max(0, idx) / scenario.output.fps);
   }
-  return { frames, anchors, boxes };
+  return { framesDir, count, anchors, boxes };
 }
 function fitCardW(cw, ch, maxW = 940, maxH = 540) {
   return Math.round(Math.min(maxW, maxH * cw / ch));
@@ -3700,7 +3710,7 @@ async function captureMotionSegment(templateUrl, props, durationMs, scenario) {
   await browser.close();
   return { buffer: await encodeMp4(frames, segmentOutput(scenario)), seconds: totalFrames / fps };
 }
-function vignetteProps(scene, take, serverBase, scenario, brand) {
+function vignetteProps(scene, take, serverBase, scenario, brand, durMs) {
   const W = scenario.viewport.width;
   const H = scenario.viewport.height;
   let crop = { x: 0, y: 0, w: W, h: H };
@@ -3724,13 +3734,13 @@ function vignetteProps(scene, take, serverBase, scenario, brand) {
   const props = {
     accent: brand.accent,
     font: brand.font,
-    dur: scene.duration / 1e3,
+    dur: durMs / 1e3,
     layout: scene.layout,
     num: scene.num ?? "",
     label: scene.label ?? "",
     caption: scene.caption ?? "",
     base: serverBase,
-    count: take.frames.length,
+    count: take.count,
     fps: scenario.output.fps,
     start,
     rate: scene.rate,
@@ -3743,13 +3753,19 @@ function vignetteProps(scene, take, serverBase, scenario, brand) {
     pushTo: scene.push?.to ?? 1
   };
   if (scene.code?.length) props.code = scene.code.join("||");
+  if (scene.push?.origin) {
+    const box = take.boxes.get(scene.push.origin);
+    if (!box) throw new Error(`vignette push.origin selector "${scene.push.origin}" not found in footage "${scene.footage}"`);
+    props.pushOx = Math.max(0, Math.min(100, (box.x + box.width / 2 - crop.x) / crop.w * 100)).toFixed(1);
+    props.pushOy = Math.max(0, Math.min(100, (box.y + box.height / 2 - crop.y) / crop.h * 100)).toFixed(1);
+  }
   if (brand.annotations && scene.fx.length > 0) {
     props.fx = scene.fx.map((fx) => {
       let coords = fx.coords;
       if (fx.selector) {
         const box = take.boxes.get(fx.selector);
         if (!box) throw new Error(`vignette fx selector "${fx.selector}" not found in footage "${scene.footage}"`);
-        coords = fx.kind === "circle" ? [box.x, box.y, box.width, box.height] : [box.x - 160, box.y + 120, box.x - 12, box.y + box.height / 2];
+        coords = fx.kind === "arrow" ? [box.x - 160, box.y + 120, box.x - 12, box.y + box.height / 2] : [box.x, box.y, box.width, box.height];
       }
       return `${fx.kind}@${coords.join(",")}@${fx.delay}`;
     }).join(";");
@@ -3766,6 +3782,7 @@ async function renderScenesTimeline(scenario, scenarioDir, onProgress) {
     if (scene.type !== "vignette") continue;
     const set = selectorsByFootage.get(scene.footage) ?? /* @__PURE__ */ new Set();
     if (scene.crop?.selector) set.add(scene.crop.selector);
+    if (scene.push?.origin) set.add(scene.push.origin);
     for (const fx of scene.fx) if (fx.selector) set.add(fx.selector);
     selectorsByFootage.set(scene.footage, set);
   }
@@ -3781,9 +3798,14 @@ async function renderScenesTimeline(scenario, scenarioDir, onProgress) {
     const m = req.url?.match(/^\/([\w-]+)\/(\d+)\.png$/);
     const take = m ? takes.get(m[1]) : void 0;
     if (take) {
-      const idx = Math.min(take.frames.length - 1, parseInt(m[2], 10));
-      res.writeHead(200, { "content-type": "image/png", "cache-control": "max-age=3600" });
-      res.end(take.frames[idx]);
+      const idx = Math.min(take.count - 1, parseInt(m[2], 10));
+      readFile3(join2(take.framesDir, `${idx}.png`)).then((png) => {
+        res.writeHead(200, { "content-type": "image/png", "cache-control": "max-age=3600" });
+        res.end(png);
+      }).catch(() => {
+        res.writeHead(404);
+        res.end();
+      });
     } else {
       res.writeHead(404);
       res.end();
@@ -3791,27 +3813,32 @@ async function renderScenesTimeline(scenario, scenarioDir, onProgress) {
   });
   await new Promise((r) => server.listen(0, r));
   const port = server.address().port;
-  const totalMs = timeline.reduce((s, sc) => s + sc.duration, 0);
+  const beatMs = scenario.audio?.bpm ? 6e4 / scenario.audio.bpm : 0;
+  const durations = timeline.map(
+    (sc) => beatMs ? Math.max(beatMs, Math.round(sc.duration / beatMs) * beatMs) : sc.duration
+  );
+  const totalMs = durations.reduce((s, d) => s + d, 0);
   let elapsedMs = 0;
   const segments = [];
   const tmp = await mkdtemp(join2(tmpdir2(), "clipwise-scenes-"));
   try {
     for (let i = 0; i < timeline.length; i++) {
       const scene = timeline[i];
+      const dur = durations[i];
       const label = scene.type === "motion" ? scene.template : `vignette(${scene.footage})`;
       onProgress?.({ scene: i + 1, total: timeline.length, label });
       const thread = brand.annotations ? {
         threadFrom: (elapsedMs / totalMs).toFixed(4),
-        threadTo: ((elapsedMs + scene.duration) / totalMs).toFixed(4)
+        threadTo: ((elapsedMs + dur) / totalMs).toFixed(4)
       } : {};
-      elapsedMs += scene.duration;
+      elapsedMs += dur;
       let segment;
       if (scene.type === "motion") {
         const url = resolveMotionTemplate(scene.template, scenarioDir);
         segment = await captureMotionSegment(
           url,
-          { accent: brand.accent, font: brand.font, dur: scene.duration / 1e3, ...scene.props, ...thread },
-          scene.duration,
+          { accent: brand.accent, font: brand.font, dur: dur / 1e3, ...scene.props, ...thread },
+          dur,
           scenario
         );
       } else {
@@ -3819,8 +3846,8 @@ async function renderScenesTimeline(scenario, scenarioDir, onProgress) {
         const url = resolveMotionTemplate("vignette", scenarioDir);
         segment = await captureMotionSegment(
           url,
-          { ...vignetteProps(scene, take, `http://localhost:${port}/${scene.footage}`, scenario, brand), ...thread },
-          scene.duration,
+          { ...vignetteProps(scene, take, `http://localhost:${port}/${scene.footage}`, scenario, brand, dur), ...thread },
+          dur,
           scenario
         );
       }
@@ -3834,13 +3861,39 @@ async function renderScenesTimeline(scenario, scenarioDir, onProgress) {
   const filters = segments.map((_, i) => `[${i}:v]format=yuv420p[v${i}]`).join(";");
   const concatInputs = segments.map((_, i) => `[v${i}]`).join("");
   const outPath = join2(tmp, "timeline.mp4");
+  let audioInput = "";
+  let audioMap = "";
+  const totalSec = totalMs / 1e3;
+  if (scenario.audio) {
+    const a = scenario.audio;
+    let audioPath;
+    if (/^https?:\/\//.test(a.file)) {
+      const hash = createHash("sha256").update(a.file).digest("hex").slice(0, 16);
+      audioPath = join2(tmpdir2(), `clipwise-audio-${hash}${a.file.match(/\.\w{2,4}$/)?.[0] ?? ".mp3"}`);
+      if (!existsSync2(audioPath)) {
+        execSync(`curl -sL -o "${audioPath}" "${a.file}"`, { stdio: ["ignore", "ignore", "pipe"] });
+      }
+    } else {
+      audioPath = isAbsolute(a.file) ? a.file : resolve(scenarioDir, a.file);
+    }
+    const af = [];
+    if (a.volume !== 1) af.push(`volume=${a.volume}`);
+    if (a.fadeIn > 0) af.push(`afade=t=in:d=${a.fadeIn / 1e3}`);
+    if (a.fadeOut > 0) af.push(`afade=t=out:st=${Math.max(0, totalSec - a.fadeOut / 1e3)}:d=${a.fadeOut / 1e3}`);
+    audioInput = `-stream_loop -1 -i "${audioPath}" `;
+    audioMap = `-map ${segments.length}:a ${af.length ? `-af "${af.join(",")}" ` : ""}-c:a aac -b:a 192k `;
+  }
   execSync(
-    `ffmpeg -y ${segments.map((s) => `-i "${s.path}"`).join(" ")} -filter_complex "${filters};${concatInputs}concat=n=${segments.length}:v=1:a=0[v]" -map "[v]" -c:v libx264 -crf 16 -preset slow -movflags +faststart "${outPath}"`,
+    `ffmpeg -y ${segments.map((s) => `-i "${s.path}"`).join(" ")} ${audioInput}-filter_complex "${filters};${concatInputs}concat=n=${segments.length}:v=1:a=0[v]" -map "[v]" ${audioMap}-t ${totalSec.toFixed(3)} -c:v libx264 -crf 16 -preset slow -movflags +faststart "${outPath}"`,
     { stdio: ["ignore", "ignore", "pipe"] }
   );
   const buffer = await readFile3(outPath);
   await rm2(tmp, { recursive: true, force: true }).catch(() => {
   });
+  for (const take of takes.values()) {
+    await rm2(take.framesDir, { recursive: true, force: true }).catch(() => {
+    });
+  }
   return buffer;
 }
 
@@ -4129,7 +4182,9 @@ var AudioConfigSchema = z.object({
   /** Fade-in duration in milliseconds. */
   fadeIn: z.number().min(0).default(0),
   /** Fade-out duration in milliseconds. */
-  fadeOut: z.number().min(0).default(0)
+  fadeOut: z.number().min(0).default(0),
+  /** 트랙 BPM — scenes 타임라인에서 지정 시 신 길이를 비트 격자에 스냅(비트 싱크 컷). */
+  bpm: z.number().min(40).max(220).optional()
 });
 var AuthConfigSchema = z.object({
   /** Path to a Playwright storageState JSON file (cookies + localStorage). */
@@ -4160,6 +4215,8 @@ var MockRouteSchema = z.object({
 var PrepareConfigSchema = z.object({
   /** 녹화에서 숨길 요소의 CSS 셀렉터 (쿠키 배너, dev 오버레이 등). */
   hide: z.array(z.string().min(1)).default([]),
+  /** 블러 처리할 요소의 CSS 셀렉터 (이메일, 금액 등 민감 정보) — 스크롤·이동을 따라간다. */
+  mask: z.array(z.string().min(1)).default([]),
   /** Date/Date.now를 이 시각으로 고정 (ISO 8601, 예: "2026-06-10T09:00:00Z"). */
   freezeTime: z.string().optional(),
   /** Math.random을 이 시드의 결정론적 PRNG로 대체. */
@@ -4193,7 +4250,7 @@ var ScreenSceneSchema = z.object({
   steps: z.array(StepSchema).min(1)
 });
 var SceneFxSchema = z.object({
-  kind: z.enum(["circle", "arrow"]),
+  kind: z.enum(["circle", "arrow", "spotlight"]),
   /** 대상 요소 셀렉터 — bounding box를 실측해 좌표로 사용. */
   selector: z.string().optional(),
   /** 명시 좌표 — circle: [x,y,w,h], arrow: [x1,y1,x2,y2]. */
@@ -4223,8 +4280,14 @@ var VignetteSceneSchema = z.object({
     /** 크롭 높이 상한 (px, 원본 기준) — 와이드 스트립 연출용. */
     maxH: z.number().optional()
   }).optional(),
-  /** 푸시인 카메라 (스케일 from→to). */
-  push: z.object({ from: z.number().default(1), to: z.number().default(1) }).optional(),
+  /** 푸시인 카메라 (스케일 from→to).
+   *  origin: 푸시 중심점 — 셀렉터(실측) 지정 시 그 요소를 향해 밀어 들어가
+   *  다음 신의 크롭과 이어지는 매치컷을 만든다. 기본은 화면 중앙 약간 위. */
+  push: z.object({
+    from: z.number().default(1),
+    to: z.number().default(1),
+    origin: z.string().optional()
+  }).optional(),
   /** 푸티지 인용 시작점 — 초(number) 또는 step 경계 anchor. */
   start: z.union([z.number(), z.object({ step: z.number().int().min(0), offset: z.number().default(0) })]).default(0),
   /** 푸티지 재생 배속. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clipwise",
-  "version": "0.9.1",
+  "version": "0.10.1",
   "description": "Scriptable cinematic screen recorder for product demos — YAML in, polished MP4 out",
   "type": "module",
   "main": "dist/index.js",

package/skills/clipwise.md

@@ -375,12 +375,14 @@ scenes:
     label: "Smart Speed"
     caption: "Loading compressed, *results crisp*"
     crop: { selector: ".panel", pad: 14, maxH: 250 }   # selector-measured, never guess pixels
-    push: { from: 1.05, to: 1 }        # push-in/out camera
+    push: { from: 1.05, to: 1, origin: ".panel" }  # origin: match-cut — push toward
+                                       # a selector so the NEXT scene's crop continues the move
     start: { step: 3, offset: 0 }      # quote footage from a step boundary (or seconds)
     rate: 1.15                         # playback speed of the quoted footage
-    fx:                                # line-draw annotations on the footage
-      - { kind: circle, selector: "#revenue", delay: 2500 }
-      - { kind: arrow, selector: ".panel", delay: 2900 }
+    fx:                                # annotations on the footage
+      - { kind: circle, selector: "#revenue", delay: 2500 }    # hand-drawn circle
+      - { kind: arrow, selector: ".panel", delay: 2900 }       # drawn arrow
+      - { kind: spotlight, selector: "#revenue", delay: 2400 } # dim everything else
     # code: ["prepare:", "  hide: [...]"]   # split layout left code card
 ```
 
@@ -395,6 +397,13 @@ scenes:
 5. **Footage effects**: in scenes mode set only `cursor:` (highlight: false) — zoom/frame/background
    are handled by the vignette compositor, not the recorder
 6. Keep one screen take (~12-15s) and let vignettes quote segments via `start: { step: N }`
+7. **Sensitive data**: `prepare.mask: [".email", ".amount"]` blurs elements at record time
+   (follows scrolling — never ask the user to fake their data)
+8. **Music**: `audio: { file: bgm.mp3, bpm: 122, fadeOut: 1500 }` muxes BGM into the final
+   video AND snaps every scene cut onto the beat grid (beat-synced cuts).
+   `file:` also accepts a URL (downloaded+cached on the user's machine — use license-free
+   sources like Mixkit, e.g. `https://assets.mixkit.co/music/132/132.mp3`, ~120bpm).
+   Track shorter than the video loops automatically; video length is always authoritative
 
 ## Critical Rules
 

package/templates/motion/vignette.html

@@ -113,6 +113,15 @@
   /* ── 선 드로잉 주석 레이어 (fx=circle@…;arrow@…) — 카드 위에 그려짐 ── */
   .annotations { position: absolute; inset: 0; z-index: 5; pointer-events: none;
     overflow: visible; }
+  /* 스포트라이트 — 대상만 남기고 주변을 디밍 (fx kind: spotlight) */
+  .spotlight { position: absolute; z-index: 4; pointer-events: none;
+    /* spread가 너무 크면 Chromium이 그림자를 클램프하므로 카드 크기 수준으로 */
+    box-shadow: 0 0 0 1400px rgba(12, 12, 16, 0.52); border-radius: 10px;
+    /* 다크 UI에서도 컷아웃이 인지되도록 은은한 악센트 림 */
+    outline: 1.5px solid color-mix(in srgb, var(--accent) 55%, transparent);
+    outline-offset: 3px;
+    opacity: 0; animation: spot-in 550ms cubic-bezier(0.4, 0, 0.2, 1) both; }
+  @keyframes spot-in { to { opacity: 1; } }
   .annotations .stroke { stroke: var(--accent); fill: none; stroke-width: 3.5;
     stroke-linecap: round; stroke-linejoin: round;
     stroke-dasharray: 1; stroke-dashoffset: 1;
@@ -178,9 +187,12 @@
     card.style.setProperty("--push-from", P.get("pushFrom") || "1");
     card.style.setProperty("--push-to", P.get("pushTo") || "1");
     const fullCrop = cw >= SRC_W;
+    // push origin — 매치컷: 다음 신의 크롭 중심을 향해 밀어 들어가도록 중심점 지정
+    const pushOx = num("pushOx", 50), pushOy = num("pushOy", 42);
     card.innerHTML = `
       ${fullCrop ? '<div class="titlebar"><i></i><i></i><i></i></div>' : ""}
-      <div class="viewport"><div class="pusher" style="animation-duration:${num("dur", 4)}s">
+      <div class="viewport"><div class="pusher"
+        style="animation-duration:${num("dur", 4)}s; transform-origin:${pushOx}% ${pushOy}%">
         <img class="footage" id="footage"
              style="width:${SRC_W * scale}px;height:${SRC_H * scale}px;left:${-cx * scale}px;top:${-cy * scale}px" />
       </div></div>`;
@@ -224,6 +236,15 @@
       for (const spec of fxSpecs) {
         const [kind, coords, delay = "0"] = spec.split("@");
         const n = coords.split(",").map(Number);
+        if (kind === "spotlight") {
+          // 푸시 레이어 안에 디밍 컷아웃 — 푸티지에 앵커링되어 카메라를 따라간다
+          const [sx, sy] = toCard(n[0], n[1]);
+          const spot = document.createElement("div");
+          spot.className = "spotlight";
+          spot.style.cssText = `left:${sx - 6}px;top:${sy - 6}px;width:${n[2] * effScale + 12}px;height:${n[3] * effScale + 12}px;animation-delay:${delay}ms`;
+          card.querySelector(".pusher").appendChild(spot);
+          continue;
+        }
         if (kind === "circle") {
           // 손그림 느낌: 살짝 큰 타원 + 미세 회전
           const [x0, y0] = toCard(n[0], n[1]);