reelforge 0.5.3 → 0.5.5

package/README.md

@@ -95,6 +95,7 @@ Run `rf <command> --help` for full details on any of these.
 |---|---|
 | `templates list [--size 1080x1920] [--type image]` | List HTML frame templates |
 | `templates preview <keyOrPath> [-o out.png]` | Render a preview from a preset key **or your own local .html file** |
+| `templates show <key> [-o file.html]` | Print or save the source HTML of any preset — copy it as a starting point for a custom template |
 | `frames render -t <keyOrPath> --title ... --text ...` | Render a single composed frame to PNG. `-t` accepts a preset key **or a local .html path** |
 | `compositions concat <v1> <v2> -o out.mp4` | FFmpeg concat (+ optional BGM) |
 | `compositions bgm -i video.mp4 --bgm bgm.mp3 -o out.mp4` | Add background music |
@@ -160,6 +161,8 @@ rf llm chat -p 'one-sentence summary of antifragile'
 #      <meta name="template:width"  content="1080">
 #      <meta name="template:height" content="1920">
 #    or pass --size 1080x1920 on the CLI.
+rf templates show 1080x1920/image_default.html -o my-brand.html   # copy a preset
+# ...edit my-brand.html to suit your style...
 rf templates preview ./my-brand.html --title "Hello" -o preview.png
 rf frames render -t ./my-brand.html --values '{"author":"Alice"}' -o frame.png
 rf pipelines standard -t "宠物" --frame-template ./my-brand.html -o final.mp4
@@ -167,14 +170,42 @@ rf pipelines standard -t "宠物" --frame-template ./my-brand.html -o final.mp4
 
 ### Custom HTML templates
 
+Easiest way to start: grab a preset as a reference.
+
+```bash
+rf templates list                                                  # see all keys
+rf templates show 1080x1920/static_default.html                    # print to stdout
+rf templates show 1080x1920/image_default.html -o my-brand.html    # save and edit
+```
+
 `{{title}}`, `{{text}}`, `{{image}}`, `{{index}}` are reserved built-ins; everything else uses the `{{name:type=default}}` DSL (`type` ∈ `text|number|color|bool`). Pass extras through `--values '{"author":"Alice"}'` (or `template_params` on the pipeline API).
 
+#### Template type — does the pipeline generate an AI image per scene?
+
+When you ship an inline template through `rf create` / `rf pipelines standard`, ReelForge needs to know whether each scene should kick off RelayX image generation. Resolution priority (high → low):
+
+1. Explicit flag — `--frame-template-type image|static|asset` (or `frame_template_type` in the API body).
+2. Inside the HTML — `<meta name="template:type" content="image">` (or `static` / `asset`).
+3. **Default: `image`** — best practice for zero-config users. If your template doesn't reference scene imagery (pure-text card, etc.), declare `static` explicitly to skip image generation and its cost.
+
+The placeholder `{{image}}` no longer doubles as a type signal — declare type explicitly.
+
 Limits and safety:
 
 - Max 2 MB per inline HTML.
 - The render sandbox blocks `file://`, loopback / private / link-local IPs, CGNAT range, cloud-metadata, and `*.local` / `*.internal` hostnames. So your template can only reference public `https`/`http` resources or `data:` URIs.
 - If the CLI is talking to a hosted server, local-path `--image` won't reach the server; either upload to `rf files upload` first or use an HTTPS URL / data: URI.
 
+#### API field reference
+
+| endpoint | inline HTML field | size field | type field |
+|---|---|---|---|
+| `POST /api/v1/frames/render` | `template_html` | `size` | — (n/a, no image generation) |
+| `POST /api/v1/templates/preview` | `template_html` | `size` | — |
+| `POST /api/v1/pipelines/standard` | `frame_template_inline` | `frame_template_size` | `frame_template_type` |
+
+The pipeline endpoint uses the `frame_template_*` prefix because it already has a `frame_template` field (preset key). The single-frame endpoints use the shorter `template_html` because they don't.
+
 ## Tip — getting unstuck
 
 Every level has `--help`:

package/dist/commands/create.js

@@ -1,4 +1,5 @@
 import fs from "node:fs/promises";
+import fsSync from "node:fs";
 import path from "node:path";
 import os from "node:os";
 import { post } from "../client.js";
@@ -13,14 +14,31 @@ function estimateUnits(body) {
     const mode = body.mode || "generate";
     const titleExplicit = !!body.title;
     const N = body.n_scenes ?? 5;
-    // Template type from filename prefix
-    const tplKey = body.frame_template || "1080x1920/static_default.html";
-    const tplBase = (tplKey.split("/").pop() || "").toLowerCase();
-    const tplType = tplBase.startsWith("static_")
-        ? "static"
-        : tplBase.startsWith("asset_")
-            ? "asset"
-            : "image";
+    // Template type resolution mirrors the server (src/lib/billing.ts):
+    //   inline HTML → explicit body.frame_template_type
+    //               → <meta name="template:type" content="..."> in the HTML
+    //               → default "image"
+    //   preset key  → parsed from the filename prefix (static_/asset_/image_)
+    let tplType;
+    if (body.frame_template_inline) {
+        if (body.frame_template_type) {
+            tplType = body.frame_template_type;
+        }
+        else {
+            const m = body.frame_template_inline.match(/<meta[^>]+name=["']template:type["'][^>]+content=["']([a-z]+)["']/i);
+            const v = m?.[1].toLowerCase();
+            tplType = v === "static" || v === "asset" || v === "image" ? v : "image";
+        }
+    }
+    else {
+        const tplKey = body.frame_template || "1080x1920/static_default.html";
+        const tplBase = (tplKey.split("/").pop() || "").toLowerCase();
+        tplType = tplBase.startsWith("static_")
+            ? "static"
+            : tplBase.startsWith("asset_")
+                ? "asset"
+                : "image";
+    }
     const mediaPerFrame = tplType === "image" ? IMAGE_UNITS : 0;
     const ttsMode = body.tts_inference_mode || "edge";
     const ttsPerFrame = ttsMode === "relayx" ? TTS_RELAYX_UNITS : 0;
@@ -30,6 +48,22 @@ function estimateUnits(body) {
     return narrations + title + imagePrompts + N * (ttsPerFrame + mediaPerFrame);
 }
 // ── Helpers ─────────────────────────────────────────────────────
+/**
+ * Distinguish a local HTML file path from a preset template key.
+ * Preset keys look like `"<size>/<file>.html"` (one slash, no dots/slashes
+ * outside that pattern). Anything starting with `./`, `../`, `/`, `~`, or
+ * containing a backslash, or that ends with `.html` and exists on disk, is
+ * treated as a local path.
+ */
+function looksLikeLocalHtmlPath(value) {
+    if (/^[.~]|^\//.test(value))
+        return true;
+    if (value.includes("\\"))
+        return true;
+    if (value.endsWith(".html") && fsSync.existsSync(value))
+        return true;
+    return false;
+}
 async function resolveText(input) {
     if (input.startsWith("@")) {
         const file = input.slice(1);
@@ -138,8 +172,23 @@ function optsToBody(opts) {
         out.tts_speed = opts.ttsSpeed;
     if (opts.imageModel !== undefined)
         out.image_model = opts.imageModel;
-    if (opts.frameTemplate !== undefined)
-        out.frame_template = opts.frameTemplate;
+    if (opts.frameTemplate !== undefined) {
+        // Local .html path → read and send as inline; preset key → send as-is.
+        if (looksLikeLocalHtmlPath(opts.frameTemplate)) {
+            const abs = path.resolve(opts.frameTemplate);
+            if (!fsSync.existsSync(abs)) {
+                throw new Error(`--frame-template: local file not found: ${abs}`);
+            }
+            out.frame_template_inline = fsSync.readFileSync(abs, "utf-8");
+        }
+        else {
+            out.frame_template = opts.frameTemplate;
+        }
+    }
+    if (opts.frameTemplateSize !== undefined)
+        out.frame_template_size = opts.frameTemplateSize;
+    if (opts.frameTemplateType !== undefined)
+        out.frame_template_type = opts.frameTemplateType;
     if (opts.promptPrefix !== undefined)
         out.prompt_prefix = opts.promptPrefix;
     if (opts.bgm !== undefined)
@@ -295,7 +344,9 @@ export function registerCreate(program) {
         .option("--min-image-prompt-words <N>", "image prompt min words", (v) => parseInt(v, 10))
         .option("--max-image-prompt-words <N>", "image prompt max words", (v) => parseInt(v, 10))
         // --- Visual ---
-        .option("--frame-template <key>", "HTML frame template, e.g. 1080x1920/image_default.html")
+        .option("--frame-template <keyOrPath>", "HTML frame template: preset key (e.g. 1080x1920/image_default.html) OR path to a local .html (auto-sent inline)")
+        .option("--frame-template-size <wxh>", "size for inline HTML when the file lacks <meta template:width|height>, e.g. 1080x1920")
+        .option("--frame-template-type <type>", "inline template type: image (default) | static | asset. Controls whether AI image generation runs per frame. Can also be set via <meta name=\"template:type\" content=\"...\"> in the HTML.")
         .option("--image-model <id>", "RelayX image model (rx-image-z | rx-image-flux | rx-image-qwen)")
         .option("--prompt-prefix <text>", "raw style prefix prepended to every image prompt (overrides --style)")
         .option("--style <preset>", "image style preset — shortcut for --prompt-prefix; see 'Style presets' below for the full list")
@@ -383,6 +434,12 @@ export function registerCreate(program) {
         "  # Free-form style — write your own prefix from scratch",
         '  rf create "..." --prompt-prefix "Studio Ghibli, pastel, dreamy"',
         "",
+        "  # Custom HTML template (auto-detected when --frame-template is a local path)",
+        "  rf create '...' --frame-template ./my-brand.html",
+        "  #   ↳ default type=image (best-practice; AI image generated per scene).",
+        "  #   ↳ pure-text template? declare `--frame-template-type static`",
+        "  #     OR add `<meta name=\"template:type\" content=\"static\">` inside the HTML.",
+        "",
         "  # Full recipe in one file",
         "  rf create --recipe ./space.recipe.json",
         "",
@@ -470,6 +527,12 @@ export function registerCreate(program) {
             ...body,
             text: body.text,
         };
+        // When the user supplied inline HTML, the DEFAULTS' `frame_template`
+        // key is irrelevant — drop it so the server-side request body stays
+        // clean and the dry-run output isn't misleading.
+        if (finalBody.frame_template_inline && finalBody.frame_template) {
+            delete finalBody.frame_template;
+        }
         // 3. Estimate cost
         const estimate = estimateUnits(finalBody);
         // 4. Dry-run: print & exit

package/dist/commands/pipelines.js

@@ -50,6 +50,7 @@ export function registerPipelines(program) {
         .option("--split-mode <mode>", "paragraph | line | sentence (mode=fixed)", "paragraph")
         .option("--frame-template <keyOrPath>", "preset key (e.g. 1080x1920/static_default.html) OR path to a local .html file", "1080x1920/static_default.html")
         .option("--frame-template-size <wxh>", "size for inline HTML when the file lacks <meta template:width|height>")
+        .option("--frame-template-type <type>", "inline type: image (default) | static | asset. Or set <meta name=\"template:type\"> in the HTML.")
         .option("--image-model <id>", "RelayX image model (rx-image-z | rx-image-flux | rx-image-qwen) — only when template requires AI images")
         .option("--prompt-prefix <text>", "style prefix prepended to image prompts")
         .option("--tts-voice <id>", "Edge TTS voice", "zh-CN-YunjianNeural")
@@ -78,6 +79,7 @@ export function registerPipelines(program) {
             n_scenes: opts.nScenes,
             split_mode: opts.splitMode,
             ...tpl,
+            frame_template_type: opts.frameTemplateType,
             image_model: opts.imageModel,
             prompt_prefix: opts.promptPrefix,
             tts_voice: opts.ttsVoice,

package/dist/commands/templates.js

@@ -1,3 +1,7 @@
+/**
+ * reelforge templates <list|preview|show>
+ */
+import fs from "node:fs/promises";
 import { get, post } from "../client.js";
 import { downloadTo } from "../utils/download.js";
 import { print, success, table } from "../utils/output.js";
@@ -58,4 +62,32 @@ export function registerTemplates(program) {
         }
         print(r);
     });
+    tpl
+        .command("show <key>")
+        .description("Print or save the source HTML of a preset template — use as a starting point for your own")
+        .helpOption("-h, --help", "show help")
+        .option("-o, --output <file>", "save HTML to this path (otherwise print to stdout)")
+        .addHelpText("after", [
+        "",
+        "Examples:",
+        "  # see what the default static template looks like",
+        "  rf templates show 1080x1920/static_default.html",
+        "",
+        "  # copy a preset and tweak it as your own brand template",
+        "  rf templates show 1080x1920/image_default.html -o my-brand.html",
+        "  # ...edit my-brand.html...",
+        "  rf frames render -t ./my-brand.html --title 'X' -o frame.png",
+        "",
+        "  Get the list of keys via `rf templates list`.",
+    ].join("\n"))
+        .action(async (key, opts) => {
+        const r = await get(`/api/v1/templates/source?key=${encodeURIComponent(key)}`);
+        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)`);
+        }
+        else {
+            process.stdout.write(r.html);
+        }
+    });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reelforge",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "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",