clipwise 0.10.1 → 0.11.0

package/dist/cli/index.js

@@ -11,7 +11,7 @@ var __export = (target, all) => {
 
 // src/script/types.ts
 import { z } from "zod";
-var SafeSelectorSchema, NavigateActionSchema, ClickActionSchema, TypeActionSchema, ScrollActionSchema, WaitActionSchema, HoverActionSchema, ScreenshotActionSchema, WaitForSelectorActionSchema, WaitForNavigationActionSchema, WaitForURLActionSchema, WaitForFunctionActionSchema, WaitForResponseActionSchema, SmartWaitActionSchema, StepActionSchema, ZoomIntensitySchema, AutoZoomConfigSchema, ZoomEffectSchema, CursorEffectSchema, BackgroundSchema, DeviceFrameSchema, SpeedRampConfigSchema, SmartSpeedConfigSchema, KeystrokeConfigSchema, WatermarkConfigSchema, EffectsConfigSchema, OutputConfigSchema, StepEffectsOverrideSchema, TransitionTypeSchema, StepSchema, AudioConfigSchema, AuthConfigSchema, MockRouteSchema, PrepareConfigSchema, MotionSceneSchema, ScreenSceneSchema, SceneFxSchema, VignetteSceneSchema, SceneSchema, ScenarioSchema;
+var SafeSelectorSchema, NavigateActionSchema, ClickActionSchema, TypeActionSchema, ScrollActionSchema, WaitActionSchema, HoverActionSchema, ScreenshotActionSchema, WaitForSelectorActionSchema, WaitForNavigationActionSchema, WaitForURLActionSchema, WaitForFunctionActionSchema, WaitForResponseActionSchema, SmartWaitActionSchema, StepActionSchema, ZoomIntensitySchema, AutoZoomConfigSchema, ZoomEffectSchema, CursorEffectSchema, BackgroundSchema, DeviceFrameSchema, SpeedRampConfigSchema, SmartSpeedConfigSchema, KeystrokeConfigSchema, WatermarkConfigSchema, EffectsConfigSchema, OutputConfigSchema, StepEffectsOverrideSchema, TransitionTypeSchema, StepSchema, AudioConfigSchema, AuthConfigSchema, MockRouteSchema, PrepareConfigSchema, MotionSceneSchema, ScreenSceneSchema, SceneFxSchema, VignetteSceneSchema, SceneSchema, CaptionSchema, ScenarioSchema;
 var init_types = __esm({
   "src/script/types.ts"() {
     "use strict";
@@ -257,7 +257,10 @@ var init_types = __esm({
       codec: z.enum(["auto", "h264", "hevc", "av1"]).default("auto"),
       // Zero-Footprint 계약 (v0.8): 모든 산출물은 .clipwise/ 아래로.
       outputDir: z.string().default(".clipwise/output"),
-      filename: z.string().default("clipwise-recording")
+      filename: z.string().default("clipwise-recording"),
+      /** scenes 전용 — 추가 출력 비율. 푸티지는 1회 녹화, 무대만 비율별 재합성해
+       *  소셜 배포용 파일을 동시 생성한다 (예: ["9:16", "1:1"]). */
+      aspects: z.array(z.enum(["16:9", "9:16", "1:1"])).default([])
     });
     StepEffectsOverrideSchema = z.object({
       zoom: ZoomEffectSchema.partial().optional(),
@@ -410,6 +413,11 @@ var init_types = __esm({
       ScreenSceneSchema,
       VignetteSceneSchema
     ]);
+    CaptionSchema = z.object({
+      text: z.string().min(1),
+      start: z.number().min(0),
+      end: z.number().min(0)
+    });
     ScenarioSchema = z.object({
       name: z.string(),
       description: z.string().optional(),
@@ -430,7 +438,9 @@ var init_types = __esm({
       /** steps 기반(클래식) 시나리오. scenes가 있으면 생략 가능. */
       steps: z.array(StepSchema).default([]),
       /** Scene System (v0.9 preview) — motion/screen/vignette 타임라인. */
-      scenes: z.array(SceneSchema).optional()
+      scenes: z.array(SceneSchema).optional(),
+      /** scenes 전용 — 선언형 캡션 트랙 (스타일은 brand accent를 따른다). */
+      captions: z.array(CaptionSchema).default([])
     }).superRefine((s, ctx) => {
       if (s.steps.length === 0 && !s.scenes?.length) {
         ctx.addIssue({
@@ -4085,12 +4095,12 @@ async function executeStepsForProbe(page, scene) {
     }
   }
 }
-function segmentOutput(scenario) {
+function segmentOutput(scenario, stageW, stageH) {
   const dpr = scenario.viewport.deviceScaleFactor ?? 1;
   return {
     ...scenario.output,
-    width: scenario.output.width * dpr,
-    height: scenario.output.height * dpr,
+    width: stageW * dpr,
+    height: stageH * dpr,
     preset: "archive"
   };
 }
@@ -4119,7 +4129,11 @@ 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 renderer = new CanvasRenderer(
+    takeScenario.effects,
+    segmentOutput(scenario, scenario.viewport.width, scenario.viewport.height),
+    scene.steps
+  );
   const framesDir = await mkdtemp(join2(tmpdir2(), `clipwise-footage-${scene.id}-`));
   let count = 0;
   for await (const f of renderer.composeStream(session.frames)) {
@@ -4139,12 +4153,12 @@ async function recordFootageTake(scenario, scene, selectors) {
 function fitCardW(cw, ch, maxW = 940, maxH = 540) {
   return Math.round(Math.min(maxW, maxH * cw / ch));
 }
-async function captureMotionSegment(templateUrl, props, durationMs, scenario) {
+async function captureMotionSegment(templateUrl, props, durationMs, scenario, stageW, stageH) {
   const fps = scenario.output.fps;
   const totalFrames = Math.round(durationMs / 1e3 * fps);
   const browser = await chromium2.launch();
   const page = await browser.newPage({
-    viewport: { width: scenario.output.width, height: scenario.output.height },
+    viewport: { width: stageW, height: stageH },
     deviceScaleFactor: scenario.viewport.deviceScaleFactor ?? 1
   });
   const params = new URLSearchParams(
@@ -4162,9 +4176,12 @@ async function captureMotionSegment(templateUrl, props, durationMs, scenario) {
     frames.push({ index: i, buffer: await page.screenshot({ type: "png" }), timestamp: t });
   }
   await browser.close();
-  return { buffer: await encodeMp4(frames, segmentOutput(scenario)), seconds: totalFrames / fps };
+  return {
+    buffer: await encodeMp4(frames, segmentOutput(scenario, stageW, stageH)),
+    seconds: totalFrames / fps
+  };
 }
-function vignetteProps(scene, take, serverBase, scenario, brand, durMs) {
+function vignetteProps(scene, take, serverBase, scenario, brand, durMs, stageW, stageH) {
   const W = scenario.viewport.width;
   const H = scenario.viewport.height;
   let crop = { x: 0, y: 0, w: W, h: H };
@@ -4202,7 +4219,8 @@ function vignetteProps(scene, take, serverBase, scenario, brand, durMs) {
     cropY: crop.y,
     cropW: crop.w,
     cropH: crop.h,
-    cardW: fitCardW(crop.w, crop.h),
+    // 카드 크기 상한은 무대(stage) 크기 비례 — 어떤 출력 비율에서도 일관된 여백
+    cardW: fitCardW(crop.w, crop.h, Math.round(stageW * 0.735), Math.round(stageH * 0.675)),
     pushFrom: scene.push?.from ?? 1,
     pushTo: scene.push?.to ?? 1
   };
@@ -4272,19 +4290,37 @@ async function renderScenesTimeline(scenario, scenarioDir, onProgress) {
     (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 totalSec = totalMs / 1e3;
+  let audioPath = null;
+  if (scenario.audio) {
+    const a = scenario.audio;
+    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 tmp = await mkdtemp(join2(tmpdir2(), "clipwise-scenes-"));
-  try {
+  const renderPass = async (stageW, stageH, passLabel) => {
+    let elapsedMs = 0;
+    const segments = [];
     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})`;
+      const label = `${passLabel}${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 + dur) / totalMs).toFixed(4)
       } : {};
+      if (scenario.captions.length > 0) {
+        thread.capsJson = JSON.stringify(scenario.captions);
+        thread.capsOffset = (elapsedMs / 1e3).toFixed(3);
+      }
       elapsedMs += dur;
       let segment;
       if (scene.type === "motion") {
@@ -4293,63 +4329,70 @@ async function renderScenesTimeline(scenario, scenarioDir, onProgress) {
           url,
           { accent: brand.accent, font: brand.font, dur: dur / 1e3, ...scene.props, ...thread },
           dur,
-          scenario
+          scenario,
+          stageW,
+          stageH
         );
       } else {
         const take = takes.get(scene.footage);
         const url = resolveMotionTemplate("vignette", scenarioDir);
         segment = await captureMotionSegment(
           url,
-          { ...vignetteProps(scene, take, `http://localhost:${port}/${scene.footage}`, scenario, brand, dur), ...thread },
+          {
+            ...vignetteProps(scene, take, `http://localhost:${port}/${scene.footage}`, scenario, brand, dur, stageW, stageH),
+            ...thread
+          },
           dur,
-          scenario
+          scenario,
+          stageW,
+          stageH
         );
       }
-      const segPath = join2(tmp, `s${i}.mp4`);
+      const segPath = join2(tmp, `${passLabel.replace(/\W/g, "")}s${i}.mp4`);
       await writeFile2(segPath, segment.buffer);
       segments.push({ path: segPath, seconds: segment.seconds });
     }
+    const filters = segments.map((_, i) => `[${i}:v]format=yuv420p[v${i}]`).join(";");
+    const concatInputs = segments.map((_, i) => `[v${i}]`).join("");
+    const vChain = `${filters};${concatInputs}concat=n=${segments.length}:v=1:a=0[v]`;
+    const finalLabel = "[v]";
+    let audioInput = "";
+    let audioMap = "";
+    if (scenario.audio && audioPath) {
+      const a = scenario.audio;
+      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 `;
+    }
+    const outPath = join2(tmp, `${passLabel.replace(/\W/g, "")}timeline.mp4`);
+    execSync(
+      `ffmpeg -y ${segments.map((s) => `-i "${s.path}"`).join(" ")} ${audioInput}-filter_complex "${vChain}" -map "${finalLabel}" ${audioMap}-t ${totalSec.toFixed(3)} -c:v libx264 -crf 16 -preset slow -movflags +faststart "${outPath}"`,
+      { stdio: ["ignore", "ignore", "pipe"] }
+    );
+    return readFile4(outPath);
+  };
+  try {
+    const buffer = await renderPass(scenario.viewport.width, scenario.viewport.height, "");
+    const extras = [];
+    for (const aspect of scenario.output.aspects) {
+      const [w, h] = ASPECT_DIMS[aspect];
+      extras.push({ label: aspect.replace(":", "x"), buffer: await renderPass(w, h, `${aspect} \xB7 `) });
+    }
+    return { buffer, extras };
   } finally {
     server.close();
-  }
-  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(" ")} ${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(() => {
+    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 ASPECT_DIMS;
 var init_runner = __esm({
   "src/scenes/runner.ts"() {
     "use strict";
@@ -4357,6 +4400,11 @@ var init_runner = __esm({
     init_prepare();
     init_canvas_renderer();
     init_video_encoder();
+    ASPECT_DIMS = {
+      "16:9": [1280, 720],
+      "9:16": [720, 1280],
+      "1:1": [960, 960]
+    };
   }
 });
 
@@ -4402,6 +4450,15 @@ function validateScenario(scenario) {
       }
     }
   }
+  for (let i = 0; i < scenario.captions.length; i++) {
+    const c = scenario.captions[i];
+    if (c.end <= c.start) {
+      errors.push(`captions #${i + 1} ("${c.text.slice(0, 20)}"): end must be greater than start`);
+    }
+  }
+  if (scenario.captions.length > 0 && !scenario.scenes?.length) {
+    warnings.push("captions are only rendered in scenes timelines (ignored for classic steps recordings)");
+  }
   if (scenario.steps.length > 0) {
     const firstStep = scenario.steps[0];
     const hasNavigate = firstStep.actions.some(
@@ -4585,7 +4642,7 @@ import { homedir } from "os";
 var program = new Command();
 program.name("clipwise").description(
   "Playwright-based cinematic screen recorder for product demos"
-).version("0.10.1");
+).version("0.11.0");
 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)"
@@ -4649,12 +4706,17 @@ program.command("record").description("Record a demo from a YAML scenario file")
       const outDir2 = scenario.output.outputDir;
       await mkdir2(outDir2, { recursive: true });
       spinner.start(`Rendering ${scenario.scenes.length}-scene timeline...`);
-      const buf = await renderScenesTimeline2(scenario, scenarioDir, ({ scene, total, label }) => {
+      const { buffer: buf, extras } = await renderScenesTimeline2(scenario, scenarioDir, ({ scene, total, label }) => {
         spinner.text = scene === 0 ? `Recording footage \u2014 ${label}...` : `Rendering scene ${scene}/${total} \u2014 ${label}...`;
       });
       const outputPath = join3(outDir2, `${scenario.output.filename}.mp4`);
       await writeFile3(outputPath, buf);
       spinner.succeed(`Timeline saved to ${chalk.bold(outputPath)} (${(buf.length / 1048576).toFixed(2)} MB)`);
+      for (const extra of extras) {
+        const extraPath = join3(outDir2, `${scenario.output.filename}-${extra.label}.mp4`);
+        await writeFile3(extraPath, extra.buffer);
+        spinner.succeed(`  + ${chalk.bold(extraPath)} (${(extra.buffer.length / 1048576).toFixed(2)} MB)`);
+      }
       console.log(chalk.green("\nDone! \u{1F3AC}"));
       return;
     }

package/dist/index.d.ts

@@ -627,6 +627,9 @@ declare const OutputConfigSchema: z.ZodObject<{
     codec: z.ZodDefault<z.ZodEnum<["auto", "h264", "hevc", "av1"]>>;
     outputDir: z.ZodDefault<z.ZodString>;
     filename: z.ZodDefault<z.ZodString>;
+    /** scenes 전용 — 추가 출력 비율. 푸티지는 1회 녹화, 무대만 비율별 재합성해
+     *  소셜 배포용 파일을 동시 생성한다 (예: ["9:16", "1:1"]). */
+    aspects: z.ZodDefault<z.ZodArray<z.ZodEnum<["16:9", "9:16", "1:1"]>, "many">>;
 }, "strip", z.ZodTypeAny, {
     format: "gif" | "mp4" | "webm" | "png-sequence";
     width: number;
@@ -636,6 +639,7 @@ declare const OutputConfigSchema: z.ZodObject<{
     codec: "auto" | "h264" | "hevc" | "av1";
     outputDir: string;
     filename: string;
+    aspects: ("16:9" | "9:16" | "1:1")[];
     preset?: "social" | "balanced" | "archive" | undefined;
 }, {
     format?: "gif" | "mp4" | "webm" | "png-sequence" | undefined;
@@ -647,6 +651,7 @@ declare const OutputConfigSchema: z.ZodObject<{
     codec?: "auto" | "h264" | "hevc" | "av1" | undefined;
     outputDir?: string | undefined;
     filename?: string | undefined;
+    aspects?: ("16:9" | "9:16" | "1:1")[] | undefined;
 }>;
 type OutputConfig = z.infer<typeof OutputConfigSchema>;
 /**
@@ -5521,6 +5526,9 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         codec: z.ZodDefault<z.ZodEnum<["auto", "h264", "hevc", "av1"]>>;
         outputDir: z.ZodDefault<z.ZodString>;
         filename: z.ZodDefault<z.ZodString>;
+        /** scenes 전용 — 추가 출력 비율. 푸티지는 1회 녹화, 무대만 비율별 재합성해
+         *  소셜 배포용 파일을 동시 생성한다 (예: ["9:16", "1:1"]). */
+        aspects: z.ZodDefault<z.ZodArray<z.ZodEnum<["16:9", "9:16", "1:1"]>, "many">>;
     }, "strip", z.ZodTypeAny, {
         format: "gif" | "mp4" | "webm" | "png-sequence";
         width: number;
@@ -5530,6 +5538,7 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         codec: "auto" | "h264" | "hevc" | "av1";
         outputDir: string;
         filename: string;
+        aspects: ("16:9" | "9:16" | "1:1")[];
         preset?: "social" | "balanced" | "archive" | undefined;
     }, {
         format?: "gif" | "mp4" | "webm" | "png-sequence" | undefined;
@@ -5541,6 +5550,7 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         codec?: "auto" | "h264" | "hevc" | "av1" | undefined;
         outputDir?: string | undefined;
         filename?: string | undefined;
+        aspects?: ("16:9" | "9:16" | "1:1")[] | undefined;
     }>>;
     /** Optional audio narration — muxed into MP4 output. */
     audio: z.ZodOptional<z.ZodObject<{
@@ -7860,6 +7870,20 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
             coords?: number[] | undefined;
         }[] | undefined;
     }>]>, "many">>;
+    /** scenes 전용 — 선언형 캡션 트랙 (스타일은 brand accent를 따른다). */
+    captions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        text: z.ZodString;
+        start: z.ZodNumber;
+        end: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        text: string;
+        start: number;
+        end: number;
+    }, {
+        text: string;
+        start: number;
+        end: number;
+    }>, "many">>;
 }, "strip", z.ZodTypeAny, {
     name: string;
     effects: {
@@ -8105,8 +8129,14 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         codec: "auto" | "h264" | "hevc" | "av1";
         outputDir: string;
         filename: string;
+        aspects: ("16:9" | "9:16" | "1:1")[];
         preset?: "social" | "balanced" | "archive" | undefined;
     };
+    captions: {
+        text: string;
+        start: number;
+        end: number;
+    }[];
     description?: string | undefined;
     auth?: {
         storageState?: string | undefined;
@@ -8625,6 +8655,7 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         codec?: "auto" | "h264" | "hevc" | "av1" | undefined;
         outputDir?: string | undefined;
         filename?: string | undefined;
+        aspects?: ("16:9" | "9:16" | "1:1")[] | undefined;
     } | undefined;
     audio?: {
         file: string;
@@ -8830,6 +8861,11 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
             coords?: number[] | undefined;
         }[] | undefined;
     })[] | undefined;
+    captions?: {
+        text: string;
+        start: number;
+        end: number;
+    }[] | undefined;
 }>, {
     name: string;
     effects: {
@@ -9075,8 +9111,14 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         codec: "auto" | "h264" | "hevc" | "av1";
         outputDir: string;
         filename: string;
+        aspects: ("16:9" | "9:16" | "1:1")[];
         preset?: "social" | "balanced" | "archive" | undefined;
     };
+    captions: {
+        text: string;
+        start: number;
+        end: number;
+    }[];
     description?: string | undefined;
     auth?: {
         storageState?: string | undefined;
@@ -9595,6 +9637,7 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
         codec?: "auto" | "h264" | "hevc" | "av1" | undefined;
         outputDir?: string | undefined;
         filename?: string | undefined;
+        aspects?: ("16:9" | "9:16" | "1:1")[] | undefined;
     } | undefined;
     audio?: {
         file: string;
@@ -9800,6 +9843,11 @@ declare const ScenarioSchema: z.ZodEffects<z.ZodObject<{
             coords?: number[] | undefined;
         }[] | undefined;
     })[] | undefined;
+    captions?: {
+        text: string;
+        start: number;
+        end: number;
+    }[] | undefined;
 }>;
 type Scenario = z.infer<typeof ScenarioSchema>;
 interface KeystrokeEvent {
@@ -10628,10 +10676,19 @@ interface SceneProgress {
     total: number;
     label: string;
 }
+interface ScenesRenderResult {
+    /** 기본 비율(viewport 크기) 렌더. */
+    buffer: Buffer;
+    /** output.aspects로 요청된 추가 비율 렌더 (label 예: "9x16"). */
+    extras: {
+        label: string;
+        buffer: Buffer;
+    }[];
+}
 /**
- * scenes 타임라인을 렌더해 MP4 버퍼를 반환한다.
+ * scenes 타임라인을 렌더한다 — 기본 비율 + output.aspects 추가 비율.
  */
-declare function renderScenesTimeline(scenario: Scenario, scenarioDir: string, onProgress?: (p: SceneProgress) => void): Promise<Buffer>;
+declare function renderScenesTimeline(scenario: Scenario, scenarioDir: string, onProgress?: (p: SceneProgress) => void): Promise<ScenesRenderResult>;
 
 /**
  * Parse a YAML string and return a validated Scenario object.

package/dist/index.js

@@ -3631,15 +3631,20 @@ async function executeStepsForProbe(page, scene) {
     }
   }
 }
-function segmentOutput(scenario) {
+function segmentOutput(scenario, stageW, stageH) {
   const dpr = scenario.viewport.deviceScaleFactor ?? 1;
   return {
     ...scenario.output,
-    width: scenario.output.width * dpr,
-    height: scenario.output.height * dpr,
+    width: stageW * dpr,
+    height: stageH * dpr,
     preset: "archive"
   };
 }
+var ASPECT_DIMS = {
+  "16:9": [1280, 720],
+  "9:16": [720, 1280],
+  "1:1": [960, 960]
+};
 async function recordFootageTake(scenario, scene, selectors) {
   const boxes = /* @__PURE__ */ new Map();
   if (selectors.length > 0) {
@@ -3665,7 +3670,11 @@ 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 renderer = new CanvasRenderer(
+    takeScenario.effects,
+    segmentOutput(scenario, scenario.viewport.width, scenario.viewport.height),
+    scene.steps
+  );
   const framesDir = await mkdtemp(join2(tmpdir2(), `clipwise-footage-${scene.id}-`));
   let count = 0;
   for await (const f of renderer.composeStream(session.frames)) {
@@ -3685,12 +3694,12 @@ async function recordFootageTake(scenario, scene, selectors) {
 function fitCardW(cw, ch, maxW = 940, maxH = 540) {
   return Math.round(Math.min(maxW, maxH * cw / ch));
 }
-async function captureMotionSegment(templateUrl, props, durationMs, scenario) {
+async function captureMotionSegment(templateUrl, props, durationMs, scenario, stageW, stageH) {
   const fps = scenario.output.fps;
   const totalFrames = Math.round(durationMs / 1e3 * fps);
   const browser = await chromium2.launch();
   const page = await browser.newPage({
-    viewport: { width: scenario.output.width, height: scenario.output.height },
+    viewport: { width: stageW, height: stageH },
     deviceScaleFactor: scenario.viewport.deviceScaleFactor ?? 1
   });
   const params = new URLSearchParams(
@@ -3708,9 +3717,12 @@ async function captureMotionSegment(templateUrl, props, durationMs, scenario) {
     frames.push({ index: i, buffer: await page.screenshot({ type: "png" }), timestamp: t });
   }
   await browser.close();
-  return { buffer: await encodeMp4(frames, segmentOutput(scenario)), seconds: totalFrames / fps };
+  return {
+    buffer: await encodeMp4(frames, segmentOutput(scenario, stageW, stageH)),
+    seconds: totalFrames / fps
+  };
 }
-function vignetteProps(scene, take, serverBase, scenario, brand, durMs) {
+function vignetteProps(scene, take, serverBase, scenario, brand, durMs, stageW, stageH) {
   const W = scenario.viewport.width;
   const H = scenario.viewport.height;
   let crop = { x: 0, y: 0, w: W, h: H };
@@ -3748,7 +3760,8 @@ function vignetteProps(scene, take, serverBase, scenario, brand, durMs) {
     cropY: crop.y,
     cropW: crop.w,
     cropH: crop.h,
-    cardW: fitCardW(crop.w, crop.h),
+    // 카드 크기 상한은 무대(stage) 크기 비례 — 어떤 출력 비율에서도 일관된 여백
+    cardW: fitCardW(crop.w, crop.h, Math.round(stageW * 0.735), Math.round(stageH * 0.675)),
     pushFrom: scene.push?.from ?? 1,
     pushTo: scene.push?.to ?? 1
   };
@@ -3818,19 +3831,37 @@ async function renderScenesTimeline(scenario, scenarioDir, onProgress) {
     (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 totalSec = totalMs / 1e3;
+  let audioPath = null;
+  if (scenario.audio) {
+    const a = scenario.audio;
+    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 tmp = await mkdtemp(join2(tmpdir2(), "clipwise-scenes-"));
-  try {
+  const renderPass = async (stageW, stageH, passLabel) => {
+    let elapsedMs = 0;
+    const segments = [];
     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})`;
+      const label = `${passLabel}${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 + dur) / totalMs).toFixed(4)
       } : {};
+      if (scenario.captions.length > 0) {
+        thread.capsJson = JSON.stringify(scenario.captions);
+        thread.capsOffset = (elapsedMs / 1e3).toFixed(3);
+      }
       elapsedMs += dur;
       let segment;
       if (scene.type === "motion") {
@@ -3839,62 +3870,68 @@ async function renderScenesTimeline(scenario, scenarioDir, onProgress) {
           url,
           { accent: brand.accent, font: brand.font, dur: dur / 1e3, ...scene.props, ...thread },
           dur,
-          scenario
+          scenario,
+          stageW,
+          stageH
         );
       } else {
         const take = takes.get(scene.footage);
         const url = resolveMotionTemplate("vignette", scenarioDir);
         segment = await captureMotionSegment(
           url,
-          { ...vignetteProps(scene, take, `http://localhost:${port}/${scene.footage}`, scenario, brand, dur), ...thread },
+          {
+            ...vignetteProps(scene, take, `http://localhost:${port}/${scene.footage}`, scenario, brand, dur, stageW, stageH),
+            ...thread
+          },
           dur,
-          scenario
+          scenario,
+          stageW,
+          stageH
         );
       }
-      const segPath = join2(tmp, `s${i}.mp4`);
+      const segPath = join2(tmp, `${passLabel.replace(/\W/g, "")}s${i}.mp4`);
       await writeFile2(segPath, segment.buffer);
       segments.push({ path: segPath, seconds: segment.seconds });
     }
+    const filters = segments.map((_, i) => `[${i}:v]format=yuv420p[v${i}]`).join(";");
+    const concatInputs = segments.map((_, i) => `[v${i}]`).join("");
+    const vChain = `${filters};${concatInputs}concat=n=${segments.length}:v=1:a=0[v]`;
+    const finalLabel = "[v]";
+    let audioInput = "";
+    let audioMap = "";
+    if (scenario.audio && audioPath) {
+      const a = scenario.audio;
+      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 `;
+    }
+    const outPath = join2(tmp, `${passLabel.replace(/\W/g, "")}timeline.mp4`);
+    execSync(
+      `ffmpeg -y ${segments.map((s) => `-i "${s.path}"`).join(" ")} ${audioInput}-filter_complex "${vChain}" -map "${finalLabel}" ${audioMap}-t ${totalSec.toFixed(3)} -c:v libx264 -crf 16 -preset slow -movflags +faststart "${outPath}"`,
+      { stdio: ["ignore", "ignore", "pipe"] }
+    );
+    return readFile3(outPath);
+  };
+  try {
+    const buffer = await renderPass(scenario.viewport.width, scenario.viewport.height, "");
+    const extras = [];
+    for (const aspect of scenario.output.aspects) {
+      const [w, h] = ASPECT_DIMS[aspect];
+      extras.push({ label: aspect.replace(":", "x"), buffer: await renderPass(w, h, `${aspect} \xB7 `) });
+    }
+    return { buffer, extras };
   } finally {
     server.close();
-  }
-  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(" ")} ${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(() => {
+    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;
 }
 
 // src/script/parser.ts
@@ -4146,7 +4183,10 @@ var OutputConfigSchema = z.object({
   codec: z.enum(["auto", "h264", "hevc", "av1"]).default("auto"),
   // Zero-Footprint 계약 (v0.8): 모든 산출물은 .clipwise/ 아래로.
   outputDir: z.string().default(".clipwise/output"),
-  filename: z.string().default("clipwise-recording")
+  filename: z.string().default("clipwise-recording"),
+  /** scenes 전용 — 추가 출력 비율. 푸티지는 1회 녹화, 무대만 비율별 재합성해
+   *  소셜 배포용 파일을 동시 생성한다 (예: ["9:16", "1:1"]). */
+  aspects: z.array(z.enum(["16:9", "9:16", "1:1"])).default([])
 });
 var StepEffectsOverrideSchema = z.object({
   zoom: ZoomEffectSchema.partial().optional(),
@@ -4299,6 +4339,11 @@ var SceneSchema = z.discriminatedUnion("type", [
   ScreenSceneSchema,
   VignetteSceneSchema
 ]);
+var CaptionSchema = z.object({
+  text: z.string().min(1),
+  start: z.number().min(0),
+  end: z.number().min(0)
+});
 var ScenarioSchema = z.object({
   name: z.string(),
   description: z.string().optional(),
@@ -4319,7 +4364,9 @@ var ScenarioSchema = z.object({
   /** steps 기반(클래식) 시나리오. scenes가 있으면 생략 가능. */
   steps: z.array(StepSchema).default([]),
   /** Scene System (v0.9 preview) — motion/screen/vignette 타임라인. */
-  scenes: z.array(SceneSchema).optional()
+  scenes: z.array(SceneSchema).optional(),
+  /** scenes 전용 — 선언형 캡션 트랙 (스타일은 brand accent를 따른다). */
+  captions: z.array(CaptionSchema).default([])
 }).superRefine((s, ctx) => {
   if (s.steps.length === 0 && !s.scenes?.length) {
     ctx.addIssue({
@@ -4417,6 +4464,15 @@ function validateScenario(scenario) {
       }
     }
   }
+  for (let i = 0; i < scenario.captions.length; i++) {
+    const c = scenario.captions[i];
+    if (c.end <= c.start) {
+      errors.push(`captions #${i + 1} ("${c.text.slice(0, 20)}"): end must be greater than start`);
+    }
+  }
+  if (scenario.captions.length > 0 && !scenario.scenes?.length) {
+    warnings.push("captions are only rendered in scenes timelines (ignored for classic steps recordings)");
+  }
   if (scenario.steps.length > 0) {
     const firstStep = scenario.steps[0];
     const hasNavigate = firstStep.actions.some(

package/package.json

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

package/skills/clipwise.md

@@ -399,6 +399,10 @@ scenes:
 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)
+9. **Social formats**: `output.aspects: ["9:16", "1:1"]` renders extra reels/feed files in the
+   same run — footage is recorded once, only the stage re-composes. Files: `name-9x16.mp4` etc.
+10. **Captions**: top-level `captions: [{ text, start, end }]` (timeline-absolute seconds)
+   burns styled caption pills into every aspect — great for sound-off social playback
 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

package/templates/motion/kinetic-type.html

@@ -91,6 +91,24 @@
   /* ── 스레드 — 영상 전체를 관통하는 한 줄의 잉크 선.
      threadFrom→threadTo 구간을 신 길이 동안 선형으로 전진시키면
      하드컷을 넘어도 같은 경로 위에서 끊김 없이 이어진다. ── */
+
+  /* ── 전역 캡션 트랙 — 타임라인 절대시각 기준, 신 경계를 넘어 이어진다.
+     ffmpeg 자막 필터(libass) 의존 없이 템플릿 레이어로 렌더 — 어떤 ffmpeg
+     빌드에서도 동작하고 폰트·브랜드 토큰을 그대로 쓴다. ── */
+  .gcap { position: absolute; left: 50%; transform: translateX(-50%);
+    bottom: 2.4%; z-index: 8; max-width: 86%;
+    font-family: var(--sans); font-weight: 600; color: var(--ink);
+    background: rgba(255, 255, 255, 0.82); border: 1px solid rgba(20, 20, 19, 0.08);
+    border-radius: 12px; padding: 0.5em 1.1em; text-align: center;
+    white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
+    opacity: 0; animation: gcap-show linear both; }
+  @keyframes gcap-show {
+    0% { opacity: 0; transform: translateX(-50%) translateY(8px); }
+    7% { opacity: 1; transform: translateX(-50%) translateY(0); }
+    93% { opacity: 1; transform: translateX(-50%) translateY(0); }
+    100% { opacity: 0; transform: translateX(-50%) translateY(0); }
+  }
+
   .thread { position: absolute; inset: 0; pointer-events: none; z-index: 2; }
   .thread path { fill: none; stroke: var(--accent); stroke-width: 2.5; opacity: 0.55;
     stroke-linecap: round;
@@ -114,7 +132,8 @@
   <script>
     const P = new URLSearchParams(location.search);
     document.documentElement.style.setProperty("--accent", P.get("accent") || "#6366f1");
-    if (P.get("size")) document.documentElement.style.setProperty("--size", P.get("size") + "px");
+    const stageScale = Math.max(0.55, Math.min(1, innerWidth / 1280));
+    if (P.get("size")) document.documentElement.style.setProperty("--size", (parseFloat(P.get("size")) * stageScale).toFixed(1) + "px");
     document.documentElement.dataset.font = P.get("font") || "editorial";
     const FX = P.get("fx") || "underline"; // underline | marker | off
 
@@ -164,13 +183,17 @@
     }
 
     // ── 스레드: 모든 신이 공유하는 동일 경로 — 구간만 다르게 전진 ──
-    const THREAD_PATH = "M -6 716 C 150 704, 320 730, 480 714 S 770 724, 940 706 S 1180 728, 1286 712";
+    // 스레드 경로 — 스테이지 크기에서 동적 생성. 두 템플릿이 동일 공식을 쓰므로
+    // 어떤 비율(16:9/9:16/1:1)에서도 신 간 연속성이 유지된다.
+    const _W = innerWidth, _H = innerHeight, _ty = _H * 0.895, _a = _H * 0.016;
+    const _f = (n) => n.toFixed(1);
+    const THREAD_PATH = `M -6 ${_f(_ty - _a * 0.3)} C ${_f(_W * 0.12)} ${_f(_ty - _a)}, ${_f(_W * 0.25)} ${_f(_ty + _a)}, ${_f(_W * 0.375)} ${_f(_ty - _a * 0.2)} S ${_f(_W * 0.6)} ${_f(_ty + _a * 0.6)}, ${_f(_W * 0.734)} ${_f(_ty - _a * 1.1)} S ${_f(_W * 0.92)} ${_f(_ty + _a)}, ${_f(_W + 6)} ${_f(_ty - _a * 0.4)}`;
     const tf = P.get("threadFrom"), tt = P.get("threadTo");
     if (tf !== null && tt !== null) {
       const durS = parseFloat(P.get("dur") || "3");
       const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
       svg.setAttribute("class", "thread");
-      svg.setAttribute("viewBox", "0 0 1280 800");
+      svg.setAttribute("viewBox", `0 0 ${_W} ${_H}`);
       svg.innerHTML = `<path d="${THREAD_PATH}" pathLength="1"
         style="--tf:${tf};--tt:${tt};animation-duration:${durS}s"/>`;
       stage.appendChild(svg);
@@ -196,6 +219,25 @@
       }
     });
 
+
+    // 전역 캡션 — capsJson(절대 start/end 초) + capsOffset(이 신의 절대 시작 초)
+    if (P.get("capsJson")) {
+      const offset = parseFloat(P.get("capsOffset") || "0");
+      const sceneDur = parseFloat(P.get("dur") || "4");
+      const capFs = Math.max(15, innerHeight * 0.026);
+      for (const c of JSON.parse(P.get("capsJson"))) {
+        const s = c.start - offset, e = c.end - offset;
+        if (e <= 0 || s >= sceneDur) continue; // 이 신과 무관
+        const el = document.createElement("div");
+        el.className = "gcap";
+        el.textContent = c.text;
+        el.style.fontSize = capFs.toFixed(1) + "px";
+        el.style.animationDelay = Math.max(0, s).toFixed(3) + "s";
+        el.style.animationDuration = (Math.min(e, sceneDur) - Math.max(0, s)).toFixed(3) + "s";
+        document.querySelector(".stage").appendChild(el);
+      }
+    }
+
     window.__clipwiseSeek = async (t) => {
       await ready;
       for (const a of document.getAnimations()) { a.pause(); a.currentTime = t; }

package/templates/motion/vignette.html

@@ -64,6 +64,24 @@
   .stage { width: 100%; height: 100%; display: flex; flex-direction: column;
     align-items: center; justify-content: center; gap: 22px; position: relative; }
 
+
+  /* ── 전역 캡션 트랙 — 타임라인 절대시각 기준, 신 경계를 넘어 이어진다.
+     ffmpeg 자막 필터(libass) 의존 없이 템플릿 레이어로 렌더 — 어떤 ffmpeg
+     빌드에서도 동작하고 폰트·브랜드 토큰을 그대로 쓴다. ── */
+  .gcap { position: absolute; left: 50%; transform: translateX(-50%);
+    bottom: 2.4%; z-index: 8; max-width: 86%;
+    font-family: var(--sans); font-weight: 600; color: var(--ink);
+    background: rgba(255, 255, 255, 0.82); border: 1px solid rgba(20, 20, 19, 0.08);
+    border-radius: 12px; padding: 0.5em 1.1em; text-align: center;
+    white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
+    opacity: 0; animation: gcap-show linear both; }
+  @keyframes gcap-show {
+    0% { opacity: 0; transform: translateX(-50%) translateY(8px); }
+    7% { opacity: 1; transform: translateX(-50%) translateY(0); }
+    93% { opacity: 1; transform: translateX(-50%) translateY(0); }
+    100% { opacity: 0; transform: translateX(-50%) translateY(0); }
+  }
+
   /* 스레드 — 카드 뒤를 지나는 연결 선 (kinetic-type.html과 동일 경로/문법) */
   .thread { position: absolute; inset: 0; pointer-events: none; z-index: 1; }
   .thread path { fill: none; stroke: var(--accent); stroke-width: 2.5; opacity: 0.55;
@@ -279,14 +297,18 @@
     const img = document.getElementById("footage");
 
     // ── 스레드 — 모든 신이 공유하는 동일 경로, 구간(threadFrom→threadTo)만 전진 ──
-    const THREAD_PATH = "M -6 716 C 150 704, 320 730, 480 714 S 770 724, 940 706 S 1180 728, 1286 712";
+    // 스레드 경로 — 스테이지 크기에서 동적 생성. 두 템플릿이 동일 공식을 쓰므로
+    // 어떤 비율(16:9/9:16/1:1)에서도 신 간 연속성이 유지된다.
+    const _W = innerWidth, _H = innerHeight, _ty = _H * 0.895, _a = _H * 0.016;
+    const _f = (n) => n.toFixed(1);
+    const THREAD_PATH = `M -6 ${_f(_ty - _a * 0.3)} C ${_f(_W * 0.12)} ${_f(_ty - _a)}, ${_f(_W * 0.25)} ${_f(_ty + _a)}, ${_f(_W * 0.375)} ${_f(_ty - _a * 0.2)} S ${_f(_W * 0.6)} ${_f(_ty + _a * 0.6)}, ${_f(_W * 0.734)} ${_f(_ty - _a * 1.1)} S ${_f(_W * 0.92)} ${_f(_ty + _a)}, ${_f(_W + 6)} ${_f(_ty - _a * 0.4)}`;
     const tf = P.get("threadFrom"), tt = P.get("threadTo");
     if (tf !== null && tt !== null) {
       const durS = parseFloat(P.get("dur") || "4");
       const stage = document.querySelector(".stage");
       const tsvg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
       tsvg.setAttribute("class", "thread");
-      tsvg.setAttribute("viewBox", "0 0 1280 800");
+      tsvg.setAttribute("viewBox", `0 0 ${_W} ${_H}`);
       tsvg.innerHTML = `<path d="${THREAD_PATH}" pathLength="1"
         style="--tf:${tf};--tt:${tt};animation-duration:${durS}s"/>`;
       stage.appendChild(tsvg);
@@ -296,6 +318,25 @@
       stage.appendChild(dot);
     }
 
+
+    // 전역 캡션 — capsJson(절대 start/end 초) + capsOffset(이 신의 절대 시작 초)
+    if (P.get("capsJson")) {
+      const offset = parseFloat(P.get("capsOffset") || "0");
+      const sceneDur = parseFloat(P.get("dur") || "4");
+      const capFs = Math.max(15, innerHeight * 0.026);
+      for (const c of JSON.parse(P.get("capsJson"))) {
+        const s = c.start - offset, e = c.end - offset;
+        if (e <= 0 || s >= sceneDur) continue; // 이 신과 무관
+        const el = document.createElement("div");
+        el.className = "gcap";
+        el.textContent = c.text;
+        el.style.fontSize = capFs.toFixed(1) + "px";
+        el.style.animationDelay = Math.max(0, s).toFixed(3) + "s";
+        el.style.animationDuration = (Math.min(e, sceneDur) - Math.max(0, s)).toFixed(3) + "s";
+        document.querySelector(".stage").appendChild(el);
+      }
+    }
+
     window.__clipwiseSeek = async (t) => {
       for (const a of document.getAnimations()) { a.pause(); a.currentTime = t; }
       if (BASE) {