reelforge 0.10.0 → 0.10.1

package/README.md

@@ -179,6 +179,8 @@ rf create "我的视频" --frame-template ./my-brand.html
 
 Inline HTML is hard-capped at 2 MB. The audio + motion + character-ref + scene-plan stages all keep working identically — only the overlay layer is yours.
 
+**Publishing to short-video platforms (Douyin / TikTok / WeChat Channels)** — the default template renders to the full 1080×1920 canvas, but those apps overlay UI on top/bottom/right and cover-crop ~96-180px on each side on taller phones. ReelForge does NOT bake platform-specific padding into the default template. For reference safe-zone numbers + a copy-pasteable CSS diff: `rf templates safezone [douyin|tiktok|wechat]`.
+
 ## Examples
 
 ```bash

package/dist/commands/templates.js

@@ -1,16 +1,26 @@
 /**
- * reelforge templates <list|preview|show>
+ * reelforge templates <list|preview|show|safezone>
  */
 import fs from "node:fs/promises";
+import kleur from "kleur";
 import { get, post } from "../client.js";
 import { downloadTo } from "../utils/download.js";
-import { print, success, table } from "../utils/output.js";
+import { isJson, print, success, table } from "../utils/output.js";
 import { buildTemplatePayload } from "./frames.js";
 export function registerTemplates(program) {
     const tpl = program
         .command("templates")
-        .description("Browse and preview HTML frame templates")
-        .helpOption("-h, --help", "show help");
+        .description("Browse templates, preview, view source, and look up platform safe zones")
+        .helpOption("-h, --help", "show help")
+        .addHelpText("after", [
+        "",
+        "Examples:",
+        "  rf templates list --size 1080x1920",
+        "  rf templates show 1080x1920/default.html -o my.html",
+        "  rf templates safezone                 # all platforms overview",
+        "  rf templates safezone douyin          # CSS diff for 抖音",
+        "  rf templates preview ./my.html -o p.png",
+    ].join("\n"));
     tpl
         .command("list")
         .description("List all HTML templates (static / image / video / asset, grouped by size)")
@@ -86,9 +96,149 @@ export function registerTemplates(program) {
         if (opts.output) {
             await fs.writeFile(opts.output, r.html, "utf-8");
             success(`Saved → ${opts.output} (${r.size}, ${r.type}, ${r.params.length} custom params)`);
+            if (/default\.html$/.test(key) && !isJson()) {
+                process.stderr.write(kleur.dim("  ↳ for short-video platform safe zones (抖音/TikTok/视频号), see ") +
+                    kleur.cyan("rf templates safezone") +
+                    "\n");
+            }
         }
         else {
             process.stdout.write(r.html);
         }
     });
+    tpl
+        .command("safezone [platform]")
+        .description("Reference safe-zone padding for short-video platforms (抖音 / TikTok / 视频号)")
+        .helpOption("-h, --help", "show help")
+        .addHelpText("after", [
+        "",
+        "Why this exists:",
+        "  Default 1080×1920 templates render to the full canvas. When a short-video",
+        "  app plays a 9:16 video on a taller phone (19.5:9 iPhone, 20:9/21:9 Android)",
+        "  it cover-crops ~96-180px each side, AND overlays its own UI on top, bottom,",
+        "  and the right action-button column. Important content near those edges gets",
+        "  cut or covered.",
+        "",
+        "  ReelForge does NOT bake platform-specific padding into the default template",
+        "  (UI changes; device crop varies). Use this command to look up reference",
+        "  numbers, then dial them into your own copy of default.html.",
+        "",
+        "Workflow:",
+        "  rf templates show 1080x1920/default.html -o my-douyin.html",
+        "  rf templates safezone douyin       # copy the CSS diff",
+        "  # paste the diff into my-douyin.html",
+        "  rf create '...' --frame-template ./my-douyin.html",
+        "",
+        "Examples:",
+        "  rf templates safezone              # overview table for all platforms",
+        "  rf templates safezone douyin       # detailed CSS diff for 抖音",
+        "  rf templates safezone tiktok",
+        "  rf templates safezone wechat       # 视频号",
+        "  rf templates safezone --json       # machine-readable",
+    ].join("\n"))
+        .action((platform) => {
+        if (isJson()) {
+            if (platform) {
+                const zone = PLATFORM_SAFEZONES[platform.toLowerCase()];
+                if (!zone) {
+                    print({ ok: false, error: `unknown platform: ${platform}`, known: Object.keys(PLATFORM_SAFEZONES) });
+                    process.exit(1);
+                }
+                print({ ok: true, platform: platform.toLowerCase(), ...zone });
+            }
+            else {
+                print({ ok: true, platforms: PLATFORM_SAFEZONES });
+            }
+            return;
+        }
+        if (platform) {
+            const key = platform.toLowerCase();
+            const zone = PLATFORM_SAFEZONES[key];
+            if (!zone) {
+                process.stderr.write(kleur.red(`✗ unknown platform: ${platform}\n`) +
+                    `  known: ${Object.keys(PLATFORM_SAFEZONES).join(", ")}\n`);
+                process.exit(1);
+            }
+            printPlatformDetail(key, zone);
+        }
+        else {
+            printPlatformOverview();
+        }
+    });
+}
+const PLATFORM_SAFEZONES = {
+    douyin: {
+        label: "Douyin (抖音)",
+        top: 250,
+        bottom: 400,
+        left: 150,
+        right: 250,
+        centerMax: 820,
+        reason: "Cover-crop on tall phones cuts ~96-180px per side; status bar ~250px; bottom caption+progress+buttons ~400px; right action-button column ~150px from the visible edge.",
+    },
+    tiktok: {
+        label: "TikTok",
+        top: 220,
+        bottom: 380,
+        left: 150,
+        right: 240,
+        centerMax: 820,
+        reason: "Same cover-crop behavior as Douyin; slightly smaller top tab area and bottom caption.",
+    },
+    wechat: {
+        label: "WeChat Channels (视频号)",
+        top: 200,
+        bottom: 350,
+        left: 120,
+        right: 120,
+        centerMax: 880,
+        reason: "Cover-crop similar; right-side action buttons are less obtrusive than 抖音/TikTok, so right padding can be smaller.",
+    },
+};
+function printPlatformOverview() {
+    process.stdout.write(kleur.bold("Reference safe-zone padding for 1080×1920 vertical video.\n") +
+        kleur.dim("Numbers cover ~90% of mainstream phones — verify on your own target devices.\n\n"));
+    table(Object.entries(PLATFORM_SAFEZONES).map(([key, z]) => ({
+        platform: key,
+        name: z.label,
+        top: z.top,
+        bottom: z.bottom,
+        left: z.left,
+        right: z.right,
+        "center-max": z.centerMax,
+    })));
+    process.stdout.write("\n" +
+        kleur.dim("CSS diff for a specific platform: ") +
+        kleur.cyan("rf templates safezone <platform>") +
+        "\n" +
+        kleur.dim("Start from default.html:           ") +
+        kleur.cyan("rf templates show 1080x1920/default.html -o my.html") +
+        "\n");
+}
+function printPlatformDetail(key, z) {
+    process.stdout.write(kleur.bold(`${z.label} — safe-zone padding for 1080×1920 vertical video.\n\n`) +
+        kleur.dim("Why: ") +
+        z.reason +
+        "\n\n" +
+        kleur.bold("Apply this CSS to your custom template (copy of default.html):\n\n") +
+        kleur.cyan(buildCssDiff(z)) +
+        "\n" +
+        kleur.dim("Note: layout=blur-bg / letterbox push title/subtitle into matte zones\n" +
+            `(y=0..420 / 1500..1920) that overlap ${z.label}'s UI heavily. For ${key}\n` +
+            "investment, layout=full + the padding above is the safest combo.\n"));
+}
+function buildCssDiff(z) {
+    return [
+        `    .title {`,
+        `      top: ${z.top}px;`,
+        `      max-width: ${z.centerMax}px;`,
+        `    }`,
+        `    .subtitle {`,
+        `      bottom: ${z.bottom}px;`,
+        `      max-width: ${z.centerMax}px;`,
+        `    }`,
+        `    body[data-brand-position$="left"]  .brand-corner { left:  ${z.left}px; }`,
+        `    body[data-brand-position$="right"] .brand-corner { right: ${z.right}px; }`,
+        "",
+    ].join("\n");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reelforge",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "description": "CLI for ReelForge Studio — AI video engine. Installs as both `reelforge` and the short alias `rf`. Every REST API exposed as a command, with --help on every level.",
   "license": "Apache-2.0",
   "type": "module",