@officexapp/vidfarm-devcli 0.21.17 → 0.21.18

package/.agents/skills/vidfarm/SKILL.md

@@ -146,6 +146,7 @@ You may be running as the **in-web AI chat** (the /editor copilot, the chat dock
 
 - **Determine the surface before claiming capabilities.** The web chat has only its declared tools and REST routes. It cannot execute arbitrary JavaScript/Python, open a shell, create a local repository script, or use the user's filesystem. Never tell a web-chat user that you ran code or wrote a script unless a dedicated declared tool actually did so. A desktop coding agent has a real shell and filesystem and MAY write/run scripts, perform arbitrary local computations over paginated API results, create reports/CSVs/JSON, edit composition files, and orchestrate long devcli workflows within the user's authorization.
 - **The web AI chat can do all three paintbrushes** — clip raws, author HTML/hyperframe motion, and generate AI media — and it drives edits directly on the live timeline. Keep small-to-medium jobs here: text/caption swaps, a scene or two replaced, single generations, captions, approve/schedule. Just do them.
+- **Every production adheres to the TikTok-native caption standard.** On-screen text lives inside the readable safe zone (**~8%–85%** of a 9:16 frame — never pinned to the top/bottom edges the phone UI clips) and uses the composition's bold font regime (**Montserrat** default / TikTok Sans, weight ≥700). Decomposed forks often inherit the source's edge-pinned caption in an off-regime font — fix it, don't inherit it. Local devcli renders auto-normalize this, but author it correctly so the editor preview matches. Full rules in `references/editor-workflows.md` ("TikTok-native caption standard").
 - **Where the web chat struggles: complex, long, multi-step transformations.** A full multi-scene re-theme, an iterative render-critique-iterate loop, heavy scripted or batch work, or anything needing a real filesystem and many sequential tool calls will hit context limits, turn/timeout ceilings, and the web editor's constraints (CSS/declarative motion only — JS animation adapters are stripped on save). Don't grind a big transformation one layer at a time in a chat turn and stall.
 - **Practical workaround — hand the heavy job to local devcli.** When a task is genuinely large or long-running, **proactively recommend the director run it locally with an AI coding agent** (Claude Code / OpenAI Codex / any capable agent): `vidfarm pull <forkId>` writes the composition + the `.harness/` grounding bundle to disk, the agent edits with the full devcli verb set and JS animation adapters, renders free with `vidfarm serve`, and `vidfarm publish` pushes it back. This is the **best-quality (B) harness's** natural home (adversarial grading with a coding agent). Frame it as "this is a big rebuild — you'll get a better, faster result running it locally with a coding agent; here's how," not as a dead end.
 - **Offer a handoff, do not impersonate the desktop agent.** When web chat reaches that boundary, offer to save a Markdown handoff in My Files containing the objective, selected template/fork IDs, asset paths, grounding, constraints, completed work, and suggested devcli commands. Create it only after the user agrees. The desktop agent should read that document, pull the referenced fork, and then use its actual code/shell capabilities.

package/.agents/skills/vidfarm/references/editor-workflows.md

@@ -344,6 +344,17 @@ Three surfaces:
 - **Editor UI (human)** — the Inspector's **Animate (Ken Burns)** dropdown on any selected image.
 - **Desktop agents (devcli)** — `vidfarm place ./work --src <img> --kind image --ken-burns zoom-in [--ken-burns-intensity 0.3]`, or fused with generation: `vidfarm generate image --prompt "…" --place ./work --ken-burns pan-left`.
 
+### TikTok-native caption standard (position + font) — always adhere
+
+Short-form is watched on a phone, and the phone's UI eats the frame's edges. **Never pin on-screen text to the extreme top or bottom** — the top ~8% sits under the status bar / "Following · For You" tabs and the bottom ~15% under the username, caption text, music marquee, and action rail. Text there is literally clipped and reads as amateur. Two rules, applied to **every** caption/title/overlay you place or inherit:
+
+- **Position → readable safe zone.** Keep the text box's vertical extent inside **~8%–85%** of canvas height (9:16). A lower-third subtitle lives around **y≈70%** (the `captions generate` default); a "me when…" / "POV:" meme line sits near the **top of the safe zone (y≈8%), not y:0**. Preserve the original top-vs-bottom anchoring — just pull it off the dead-zone edge, don't recenter everything. Also keep wide captions clear of the **right ~12%** action rail (a centered box at `x:10 width:80` is safe).
+- **Font → the composition regime.** Use the bundled display fonts only — **Montserrat** (bold default, weight ≥700), **TikTok Sans**, Abel, Source Code Pro, Yesteryear. Don't request a font the composition doesn't import (it silently falls back). For captions, heavy weight + an outline/pill background (`spotlight` preset, `background_style:"outline"`) is the TikTok-native look.
+
+**A common trap: decomposed templates mirror the source's caption placement**, so a forked meme can arrive with its caption pinned at `top:0` in a non-regime font. When you re-theme or recaption, **fix it to the standard** rather than inheriting the edge-pinned original. When placing text yourself (`set_captions`, `set_layer_text`, `add_layer`, devcli `place`/`captions`), set `y`/`font_family` to the standard from the start.
+
+> Local devcli renders enforce this automatically: `renderCompositionLocally` runs `normalizeTikTokCaptionLayout` (src/devcli/composition-edit.ts) on every production, clamping caption/text layers into the 8%–85% safe zone and coercing off-regime primary fonts to Montserrat. It's a safety net, not a license to author edge-pinned captions — get it right in the composition so the editor preview and any cloud render match.
+
 ### Animated captions — word-by-word caption styles (TikTok/CapCut)
 
 Compositions support **first-class animated captions**: caption layers whose words animate one at a time, synced to the spoken audio, identical in the editor preview and both render paths. A caption *run* is one layer per cue (a page of ~3-5 words) on a shared track; each layer carries `data-caption-animation="<preset>"` and per-word `<span data-cap-word>` timing — no keyframe authoring, and the text stays editable like any text layer.

package/SKILL.director.md

@@ -146,6 +146,7 @@ You may be running as the **in-web AI chat** (the /editor copilot, the chat dock
 
 - **Determine the surface before claiming capabilities.** The web chat has only its declared tools and REST routes. It cannot execute arbitrary JavaScript/Python, open a shell, create a local repository script, or use the user's filesystem. Never tell a web-chat user that you ran code or wrote a script unless a dedicated declared tool actually did so. A desktop coding agent has a real shell and filesystem and MAY write/run scripts, perform arbitrary local computations over paginated API results, create reports/CSVs/JSON, edit composition files, and orchestrate long devcli workflows within the user's authorization.
 - **The web AI chat can do all three paintbrushes** — clip raws, author HTML/hyperframe motion, and generate AI media — and it drives edits directly on the live timeline. Keep small-to-medium jobs here: text/caption swaps, a scene or two replaced, single generations, captions, approve/schedule. Just do them.
+- **Every production adheres to the TikTok-native caption standard.** On-screen text lives inside the readable safe zone (**~8%–85%** of a 9:16 frame — never pinned to the top/bottom edges the phone UI clips) and uses the composition's bold font regime (**Montserrat** default / TikTok Sans, weight ≥700). Decomposed forks often inherit the source's edge-pinned caption in an off-regime font — fix it, don't inherit it. Local devcli renders auto-normalize this, but author it correctly so the editor preview matches. Full rules in `references/editor-workflows.md` ("TikTok-native caption standard").
 - **Where the web chat struggles: complex, long, multi-step transformations.** A full multi-scene re-theme, an iterative render-critique-iterate loop, heavy scripted or batch work, or anything needing a real filesystem and many sequential tool calls will hit context limits, turn/timeout ceilings, and the web editor's constraints (CSS/declarative motion only — JS animation adapters are stripped on save). Don't grind a big transformation one layer at a time in a chat turn and stall.
 - **Practical workaround — hand the heavy job to local devcli.** When a task is genuinely large or long-running, **proactively recommend the director run it locally with an AI coding agent** (Claude Code / OpenAI Codex / any capable agent): `vidfarm pull <forkId>` writes the composition + the `.harness/` grounding bundle to disk, the agent edits with the full devcli verb set and JS animation adapters, renders free with `vidfarm serve`, and `vidfarm publish` pushes it back. This is the **best-quality (B) harness's** natural home (adversarial grading with a coding agent). Frame it as "this is a big rebuild — you'll get a better, faster result running it locally with a coding agent; here's how," not as a dead end.
 - **Offer a handoff, do not impersonate the desktop agent.** When web chat reaches that boundary, offer to save a Markdown handoff in My Files containing the objective, selected template/fork IDs, asset paths, grounding, constraints, completed work, and suggested devcli commands. Create it only after the user agrees. The desktop agent should read that document, pull the referenced fork, and then use its actual code/shell capabilities.
@@ -863,6 +864,17 @@ Three surfaces:
 - **Editor UI (human)** — the Inspector's **Animate (Ken Burns)** dropdown on any selected image.
 - **Desktop agents (devcli)** — `vidfarm place ./work --src <img> --kind image --ken-burns zoom-in [--ken-burns-intensity 0.3]`, or fused with generation: `vidfarm generate image --prompt "…" --place ./work --ken-burns pan-left`.
 
+### TikTok-native caption standard (position + font) — always adhere
+
+Short-form is watched on a phone, and the phone's UI eats the frame's edges. **Never pin on-screen text to the extreme top or bottom** — the top ~8% sits under the status bar / "Following · For You" tabs and the bottom ~15% under the username, caption text, music marquee, and action rail. Text there is literally clipped and reads as amateur. Two rules, applied to **every** caption/title/overlay you place or inherit:
+
+- **Position → readable safe zone.** Keep the text box's vertical extent inside **~8%–85%** of canvas height (9:16). A lower-third subtitle lives around **y≈70%** (the `captions generate` default); a "me when…" / "POV:" meme line sits near the **top of the safe zone (y≈8%), not y:0**. Preserve the original top-vs-bottom anchoring — just pull it off the dead-zone edge, don't recenter everything. Also keep wide captions clear of the **right ~12%** action rail (a centered box at `x:10 width:80` is safe).
+- **Font → the composition regime.** Use the bundled display fonts only — **Montserrat** (bold default, weight ≥700), **TikTok Sans**, Abel, Source Code Pro, Yesteryear. Don't request a font the composition doesn't import (it silently falls back). For captions, heavy weight + an outline/pill background (`spotlight` preset, `background_style:"outline"`) is the TikTok-native look.
+
+**A common trap: decomposed templates mirror the source's caption placement**, so a forked meme can arrive with its caption pinned at `top:0` in a non-regime font. When you re-theme or recaption, **fix it to the standard** rather than inheriting the edge-pinned original. When placing text yourself (`set_captions`, `set_layer_text`, `add_layer`, devcli `place`/`captions`), set `y`/`font_family` to the standard from the start.
+
+> Local devcli renders enforce this automatically: `renderCompositionLocally` runs `normalizeTikTokCaptionLayout` (src/devcli/composition-edit.ts) on every production, clamping caption/text layers into the 8%–85% safe zone and coercing off-regime primary fonts to Montserrat. It's a safety net, not a license to author edge-pinned captions — get it right in the composition so the editor preview and any cloud render match.
+
 ### Animated captions — word-by-word caption styles (TikTok/CapCut)
 
 Compositions support **first-class animated captions**: caption layers whose words animate one at a time, synced to the spoken audio, identical in the editor preview and both render paths. A caption *run* is one layer per cue (a page of ~3-5 words) on a shared track; each layer carries `data-caption-animation="<preset>"` and per-word `<span data-cap-word>` timing — no keyframe authoring, and the text stays editable like any text layer.

package/dist/src/devcli/composition-edit.js

@@ -377,6 +377,91 @@ export function insertMediaLayer(html, opts) {
     return { html: serialize(document), layerKey: id };
 }
 const CAPTION_DEFAULT_FRAME = { x: 10, y: 70, width: 80, height: 14 };
+// ── TikTok-native caption standard ────────────────────────────────────────────
+// A 9:16 phone feed hides the extreme top and bottom of every frame behind
+// platform chrome: the top ~8% sits under the status bar / "Following · For You"
+// tabs, and the bottom ~15% under the username, caption text, music marquee, and
+// action rail. Text pinned into those bands reads as amateur AND gets literally
+// clipped. So a TikTok-native caption lives inside a readable band, and uses the
+// composition's own bold display font — not whatever font the source happened to
+// bake in. `captions generate` already defaults to y:70 / Montserrat, but a
+// DECOMPOSED template mirrors the source's edge-pinned caption (e.g. a "me when…"
+// meme caption at top:0), so we normalize at render time to guarantee every LOCAL
+// production adheres regardless of how the composition was authored.
+export const TIKTOK_CAPTION_SAFE_ZONE = { top: 8, bottom: 85 }; // % of canvas height
+// The composition font regime — mirrors COMPOSITION_FONT_IMPORT's family list in
+// services/studio-project-adapter.ts. A caption/text layer whose primary family
+// is outside this set isn't even imported (so it silently falls back at render),
+// which means coercing it to the bold default is strictly an improvement.
+const CAPTION_FONT_REGIME = ["tiktok sans", "montserrat", "abel", "source code pro", "yesteryear"];
+const CAPTION_REGIME_FALLBACK_FONT = "Montserrat";
+const CAPTION_FONT_FALLBACK_CHAIN = "'Montserrat', 'TikTok Sans', Abel, sans-serif";
+function setStylePercent(node, prop, value) {
+    if (node?.style)
+        node.style[prop] = `${Number(value.toFixed(2))}%`;
+}
+// Pull a caption/text layer's vertical position into the readable safe band,
+// PRESERVING its top-vs-bottom anchoring (a top "me when…" meme stays near the
+// top of the band; a lower-third subtitle stays low) — we only nudge layers that
+// spill into the edge dead-zones, never re-center ones already safe.
+function clampCaptionIntoSafeZone(top, height) {
+    if (top === undefined)
+        return null;
+    const h = height !== undefined && height > 0 ? height : CAPTION_DEFAULT_FRAME.height;
+    const { top: safeTop, bottom: safeBottom } = TIKTOK_CAPTION_SAFE_ZONE;
+    // Bottom edge of the band the box may occupy without its content crossing safeBottom.
+    const maxTop = Math.max(safeTop, safeBottom - h);
+    let next = top;
+    if (next < safeTop)
+        next = safeTop;
+    else if (next > maxTop)
+        next = maxTop;
+    return Math.abs(next - top) < 0.01 ? null : next;
+}
+/**
+ * Enforce the TikTok-native caption standard on a composition: keep every
+ * caption/text layer inside the readable safe zone (off the top/bottom UI
+ * dead-zones) and coerce any off-regime primary font to the bold default. Pure
+ * function — returns the rewritten HTML plus a change count/notes for logging.
+ * Idempotent: a composition already conformant is returned unchanged.
+ */
+export function normalizeTikTokCaptionLayout(html) {
+    let document, root;
+    try {
+        ({ document, root } = readCompositionDoc(html));
+    }
+    catch {
+        return { html, changed: false, moved: 0, refont: 0, notes: [] };
+    }
+    const nodes = Array.from(root.querySelectorAll('[data-layer-kind="caption"], [data-layer-kind="text"]'));
+    let moved = 0;
+    let refont = 0;
+    const notes = [];
+    for (const node of nodes) {
+        // Position: clamp into the safe band.
+        const top = stylePercent(node, "top");
+        const height = stylePercent(node, "height");
+        const clamped = clampCaptionIntoSafeZone(top, height);
+        if (clamped !== null) {
+            setStylePercent(node, "top", clamped);
+            moved += 1;
+            const label = node.getAttribute?.("data-label") || node.getAttribute?.("data-hf-id") || "caption";
+            notes.push(`moved "${String(label).slice(0, 32)}" top ${top}%→${Number(clamped.toFixed(1))}% (safe zone)`);
+        }
+        // Font: coerce off-regime primary family to the bold default.
+        const primary = String(node.getAttribute?.("data-font-family") || "").trim();
+        if (primary && !CAPTION_FONT_REGIME.includes(primary.toLowerCase())) {
+            node.setAttribute?.("data-font-family", CAPTION_REGIME_FALLBACK_FONT);
+            if (node.style)
+                node.style.fontFamily = CAPTION_FONT_FALLBACK_CHAIN;
+            refont += 1;
+            notes.push(`refont "${primary.slice(0, 24)}"→${CAPTION_REGIME_FALLBACK_FONT} (regime)`);
+        }
+    }
+    if (!moved && !refont)
+        return { html, changed: false, moved: 0, refont: 0, notes: [] };
+    return { html: serialize(document), changed: true, moved, refont, notes };
+}
 function resolveCaptionLook(opts) {
     const preset = captionStylePresetById(opts.style)
         ?? (opts.animation ? null : CAPTION_STYLE_PRESETS[0]);

package/dist/src/devcli/local-render.js

@@ -20,6 +20,7 @@ import os from "node:os";
 import path from "node:path";
 import { prepareProjectMediaForRender } from "../lib/render-media-prep.js";
 import { runHyperframesCommand } from "./hyperframes-cli.js";
+import { normalizeTikTokCaptionLayout } from "./composition-edit.js";
 // Same invariant as the backend's forceEvenCompositionDimensions: libx264
 // (yuv420p) rejects odd frame sizes, so round odd data-width/height down.
 function forceEvenDimensions(html) {
@@ -77,6 +78,20 @@ export async function renderCompositionLocally(input) {
     let prepNotes = [];
     try {
         let html = forceEvenDimensions(input.compositionHtml);
+        // TikTok-native caption standard: keep on-screen text off the top/bottom UI
+        // dead-zones and on the composition's bold font regime. Runs on every local
+        // production so a decomposed template that mirrored the source's edge-pinned
+        // caption still renders readable. Idempotent + best-effort (never blocks a render).
+        try {
+            const tiktok = normalizeTikTokCaptionLayout(html);
+            if (tiktok.changed) {
+                html = tiktok.html;
+                log("caption_safe_zone.normalized", { moved: tiktok.moved, refont: tiktok.refont, notes: tiktok.notes });
+            }
+        }
+        catch (error) {
+            log("caption_safe_zone.failed", { error: error instanceof Error ? error.message : String(error) });
+        }
         // Download-once/cut-segments pass — the same prep the backend renders run,
         // so a timeline that reuses one long source N times stays fast locally.
         try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@officexapp/vidfarm-devcli",
-  "version": "0.21.17",
+  "version": "0.21.18",
   "description": "Local bridge for the Vidfarm Trackpad Editor. `vidfarm serve <template_id>` boots the FULL editor on localhost (disk-backed records/storage, free in-process render); edit composition.html on disk (Claude Code, Codex, etc.) and the browser live-morphs it.",
   "type": "module",
   "bin": {