@clipwright/core 0.33.0 → 0.35.0

package/dist/skills.js

@@ -1,10 +1,99 @@
 import { z } from "zod";
+import { ASSET_KINDS, ASSET_MEDIA_TYPES, assetId } from "./asset-identity.js";
 import { longFormQuoteSchema } from "./long-form-pricing.js";
+import { partsLineSchema } from "./parts-pricing.js";
 import { RESOLVED_TIMELINE_MAX_SLOTS } from "./long-form-profile.js";
 import { brollPolicy } from "./broll-policy.js";
 import { countWords } from "./pacing.js";
-import { cutToNothingError, DEFAULT_TTS_MODEL, GOOGLE_TTS_MODEL, isModelVoiceName, MODEL_DEFAULT_VOICE_BY_GENDER, MODEL_VOICE_MODEL, resolveTtsModel, RUSSIAN_TTS_MODEL, MAX_SCRIPT_CHARS, SCRIPT_LENGTH_DESCRIPTION, speaksOwnVoices, STRESS_MARKING_DESCRIPTION, ttsScriptLimitError, TTS_MODELS, isVoicePresetName, VOICE_ID_PATTERN, VOICE_NAME_PATTERN, VOICE_PRESET_NAMES, } from "./voices.js";
-export const CAPTION_STYLES = ["hormozi", "tiktok", "minimal"];
+import { pauseTrim, VOICE_PACE_MAX, VOICE_PACE_MIN } from "./reference-voice.js";
+import { lexicalTokens, quoteOccurrences } from "./semantic-inserts.js";
+import { INSERT_TRANSITIONS, LAYER_ENTERS, layerRefusals, LAYOUT_WINDOW_KINDS, MAX_LAYOUT_WINDOWS, MAX_OVERLAYS, OVERLAY_POSITIONS, PRESENTER_FRAMINGS } from "./ugc-layers.js";
+import { FRAMING_SIZES, FRAMING_TRANSITIONS, framingRefusals, MAX_FRAMING } from "./ugc-framing.js";
+import { stagingFaceRect, stagingRect } from "./reference-staging.js";
+import { CALL_PHONE_DEFAULTS, CALL_SPEAKERS, CALL_STAGE_MAX_ENTER_SEC, CALL_STAGE_MAX_LEAD_SEC, CALL_STAGE_SIDES, callRefusals, DEFAULT_CALL_VOICES, MAX_CALL_CHARS, MAX_CALL_LINE_CHARS, MAX_CALL_LINES, MAX_CALL_SEC } from "./ugc-call.js";
+import { editSoundRefusals, editSounds, MAX_TEMPLATE_MEDIA, MAX_TEMPLATES, TEMPLATE_KIND_IDS, TEMPLATE_PLACEMENTS, templateCatalogText, templateRefusals, templateSounds, templateTheme } from "./templates/index.js";
+import { callout } from "./templates/callout.js";
+import { checklist } from "./templates/checklist.js";
+import { compare } from "./templates/compare.js";
+import { endCard } from "./templates/end-card.js";
+import { lowerThird } from "./templates/lower-third.js";
+import { notification } from "./templates/notification.js";
+import { phoneCall } from "./templates/phone-call.js";
+import { progress } from "./templates/progress.js";
+import { quote } from "./templates/quote.js";
+import { rating } from "./templates/rating.js";
+import { stat } from "./templates/stat.js";
+import { tag } from "./templates/tag.js";
+import { titleCard } from "./templates/title-card.js";
+import { cutToNothingError, DEFAULT_TTS_MODEL, GOOGLE_TTS_MODEL, isModelVoiceName, MODEL_DEFAULT_VOICE_BY_GENDER, MODEL_VOICE_MODEL, resolveTtsModel, MAX_SCRIPT_CHARS, SCRIPT_LENGTH_DESCRIPTION, speaksOwnVoices, STRESS_MARKING_DESCRIPTION, ttsScriptLimitError, TTS_MODELS, isVoicePresetName, VOICE_ID_PATTERN, VOICE_NAME_PATTERN, VOICE_PRESET_NAMES, } from "./voices.js";
+/** Caption looks the renderer draws, each a fixed font, colours, placement and word animation. */
+export const CAPTION_PRESETS = {
+    hormozi: "the default: heavy white uppercase with a thick black outline, up to three words per cue, one keyword per cue in yellow " +
+        "(emphasised, else the longest non-stop-word)",
+    accent: "condensed bold white uppercase, no outline, up to three words per cue, one keyword per cue in orange " +
+        "(emphasised, else the longest non-stop-word)",
+    tiktok: "bold rounded uppercase, one or two words at a time; the spoken word turns yellow and grows",
+    youtube: "clean bold sans-serif, five words on a dark rounded box near the bottom; words fade in, the spoken word in red",
+    instagram: "comic uppercase with a pink outline, two words at a time; the spoken word pops in orange",
+    minimalist: "plain sans-serif, five words on a half-transparent dark band, gentle fade",
+    neon: "cyan uppercase with a magenta outline, two words at a time; the spoken word pops in white",
+    genz: "large comic uppercase, one word at a time, slamming in with a pink highlight",
+    campfire: "rounded comic uppercase, three words; spoken words light up gold and stay lit",
+    midnight: "spooky uppercase, two words, slow fade; the spoken word in red",
+    plottwist: "heavy sans-serif, three words; the spoken word turns sky blue and grows",
+    headline: "tall condensed uppercase on a solid black band, three words; the spoken word scales up in yellow",
+    promo: "heavy sans-serif on a blue pill, three words; the spoken word pops in yellow",
+    lecture: "readable sans-serif, six words on a dark rounded box; the spoken word in green",
+    highlighter: "heavy sans-serif, four words; spoken words turn lime and stay lit",
+    studio: "sans-serif, seven words typed in on a blurred dark box; the spoken word in amber",
+    broadcast: "outlined sans-serif, eight words low in the frame; the spoken word in pale yellow",
+    arcade: "blocky yellow uppercase, two words; the spoken word bounces in white",
+    clutch: "brush uppercase, one word at a time, slamming in green",
+    bubblegum: "rounded display letters with a pink outline, two words; the spoken word bounces in yellow",
+    crayon: "marker handwriting with a navy outline, two words; the spoken word pops in orange",
+    lyrics: "handwritten script, five words; spoken words light up pink and stay lit",
+    bassdrop: "outlined display uppercase, one word at a time, scaling in orange",
+    punch: "mid-frame setup and punch: a small white lead-in line over one or two large blue glowing keywords; other words small and white",
+};
+export const CAPTION_PRESET_IDS = Object.keys(CAPTION_PRESETS);
+/** An earlier style name kept valid. */
+export const CAPTION_STYLE_ALIASES = { minimal: "minimalist" };
+export const CAPTION_STYLES = [...CAPTION_PRESET_IDS, ...Object.keys(CAPTION_STYLE_ALIASES)];
+/** The preset a style name draws: an alias resolves to its preset. */
+export function captionPresetOf(style) {
+    return style in CAPTION_STYLE_ALIASES ? CAPTION_STYLE_ALIASES[style] : style;
+}
+const CAPTION_STYLE_DESCRIPTION = "Caption look when captions=true. " +
+    CAPTION_PRESET_IDS.map((id) => `${id}: ${CAPTION_PRESETS[id]}.`).join(" ") +
+    " Alias: minimal draws minimalist. A font that cannot draw the script's letters is replaced by a plain sans-serif." +
+    " Previews: https://clipwright.io/captions";
+export const MAX_CAPTION_EMPHASIS = 20;
+export const MAX_CAPTION_EMPHASIS_CHARS = 40;
+/** `full` captions every spoken word; `highlights` only the windows around `caption_emphasis` quotes. */
+export const CAPTION_MODES = ["full", "highlights"];
+/** Where captions sit, as a percentage of the height: above the middle the top edge, below it the bottom edge (#884). */
+export const CAPTION_POSITION_VERTICAL = { top: 20, middle: 50, lower: 70, bottom: 80 };
+export const CAPTION_POSITIONS = Object.keys(CAPTION_POSITION_VERTICAL);
+/** `punch`: a small lead-in line over the quote as a large glowing keyword; `pill`: the quote alone in a rounded pill; */
+/** `color`: the quote in the style's accent colour, same size. */
+export const CAPTION_EMPHASIS_LOOKS = ["punch", "pill", "color"];
+const emphasisQuote = z.string().min(1).max(MAX_CAPTION_EMPHASIS_CHARS).refine((text) => text.trim().length > 0);
+export const captionEmphasisItem = z.union([emphasisQuote,
+    z.object({ quote: emphasisQuote, look: z.enum(CAPTION_EMPHASIS_LOOKS).optional(),
+        punch_in: z.boolean().optional().describe("Long form only: zoom into the presenter while the quote is spoken. " +
+            "Drawn only where captions are drawn and the presenter is on screen; otherwise warnings[] names it.") }).strict()]);
+/** An emphasis item as quote, look and punch-in; a plain string, or an object without a look, takes the preset's look. */
+export function captionEmphasisOf(item) {
+    return typeof item === "string" ? { quote: item, look: undefined }
+        : { quote: item.quote, look: item.look, ...(item.punch_in === true ? { punchIn: true } : {}) };
+}
+/** Composition semantics of a run, written at admission: 2 draws captions and crops pictures */
+/** to fill the frame; a run stored without it keeps the earlier render, so it re-renders the same. */
+export const UGC_COMPOSITION_VERSION = 2;
+export function compositionVersionOf(storedInput) {
+    return storedInput !== null && typeof storedInput === "object" &&
+        storedInput.composition_version === UGC_COMPOSITION_VERSION ? 2 : 1;
+}
 export const LOOKS = ["natural", "commercial", "raw_iphone"];
 /** Public formats = formats MEASURED live, not the vendor docs: declaring more would */
 /** accept values the pipeline later rejects. */
@@ -54,6 +143,8 @@ export const MAKE_FACELESS_AGENT_PROTOCOL = "Call quote_faceless first and show
     "starts the run and returns a run_id IMMEDIATELY. Then poll get_run with that run_id until the " +
     "state is 'succeeded' (video_url) or 'failed'. Pass attempt=2,3,… to deliberately start a NEW " +
     "run for the same input.";
+const IMAGE_MOTION_DESCRIPTION = "Optional picture zoom. A picture always fills the frame, cut to its shape when the shapes differ " +
+    "(warnings[] names the share cut). amount is the zoom beyond filling: in grows from 1 to 1+amount, out shrinks from 1+amount to 1. No motion by default.";
 /** One clip segment. `segments` makes `script` optional, changing `required[]` in `tools/list`, */
 /** so the shape was declared once up front instead of changing the public form later. */
 export const ugcSegment = z.object({
@@ -69,7 +160,7 @@ export const ugcSegment = z.object({
     image_motion: z.object({
         direction: z.enum(["in", "out"]),
         amount: z.number().min(0).lt(1),
-    }).optional().describe("Optional image zoom: amount is the fractional reduction from fully contained size. No motion by default; no foreground crop."),
+    }).optional().describe(IMAGE_MOTION_DESCRIPTION),
 }).superRefine((segment, context) => {
     if (segment.kind === "actor") {
         for (const field of ["media_type", "duration_seconds", "image_motion"]) {
@@ -88,24 +179,150 @@ export const ugcSegment = z.object({
         }
     }
 });
+const insertId = z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/);
+const wordAnchor = z.union([
+    z.object({ startWord: z.number().int().nonnegative(), endWord: z.number().int().positive() })
+        .strict().refine(range => range.endWord > range.startWord, { message: "endWord must be greater than startWord" }),
+    z.object({ quote: z.string().min(1).max(MAX_SCRIPT_CHARS).refine(text => text.trim().length > 0),
+        occurrence: z.number().int().nonnegative().optional() }).strict(),
+]);
+const mediaSource = {
+    media_url: z.string().url().max(MAX_URL_LENGTH).startsWith("https://").optional()
+        .describe("Public https URL of the media. Pass exactly one of media_url or asset_id."),
+    media_type: z.enum(["image", "video"])
+        .describe("image (PNG or JPEG) or video (MP4, H.264 or HEVC, 8-bit SDR). A video plays muted from its first frame and is cut where its words end; " +
+        "one shorter than its words holds its last frame, and warnings[] names it."),
+};
+const hasOneSource = (item) => (item.media_url === undefined) !== (item.asset_id === undefined);
+const ONE_SOURCE = { path: ["media_url"], message: "pass exactly one of media_url or asset_id" };
 export const ugcInsert = z.object({
-    id: z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/),
-    media_url: z.string().url().max(MAX_URL_LENGTH).startsWith("https://"),
-    media_type: z.enum(["image", "video"]),
-    anchor: z.union([
-        z.object({ startWord: z.number().int().nonnegative(), endWord: z.number().int().positive() })
-            .strict().refine(range => range.endWord > range.startWord, { message: "endWord must be greater than startWord" }),
-        z.object({ quote: z.string().min(1).max(MAX_SCRIPT_CHARS).refine(text => text.trim().length > 0),
-            occurrence: z.number().int().nonnegative().optional() }).strict(),
-    ]),
+    id: insertId,
+    media_url: mediaSource.media_url,
+    asset_id: assetId.optional()
+        .describe("A ready PNG or JPEG image or MP4 video from your own assets (list_assets), instead of media_url. Pass exactly one of the two; " +
+        "media_type must match the asset's kind."),
+    media_type: mediaSource.media_type,
+    anchor: wordAnchor,
     cover_words: z.number().int().positive().max(10000).optional()
         .describe("How many spoken words this insert covers, counted from the first word of its anchor. " +
         "Omitted means the anchored words only. The insert ends where the first uncovered word begins, " +
         "so inserts whose coverage meets are adjacent frame for frame and leave no actor shot between them."),
-    image_motion: z.object({ direction: z.enum(["in", "out"]), amount: z.number().min(0).lt(1) }).strict().optional(),
+    image_motion: z.object({ direction: z.enum(["in", "out"]), amount: z.number().min(0).lt(1) }).strict().optional()
+        .describe(IMAGE_MOTION_DESCRIPTION),
+    transition: z.enum(INSERT_TRANSITIONS).optional()
+        .describe("How the insert comes in and goes out: cut (default), wipe (slides across the presenter), flash (a white flash on the cut) " +
+        "or zoom (eases in from a closer framing). It never moves the insert's start or end."),
 }).strict().refine(insert => insert.image_motion === undefined || insert.media_type === "image", {
     path: ["image_motion"], message: "image_motion requires media_type=image",
+}).refine(hasOneSource, ONE_SOURCE);
+const layerMedia = {
+    id: insertId.describe("Unique across inserts, overlays and layout_windows."),
+    ...mediaSource,
+    asset_id: assetId.optional()
+        .describe("A ready PNG or JPEG image or MP4 video from your own assets (list_assets), instead of media_url. Pass exactly one of the two; " +
+        "media_type must match the asset's kind."),
+    anchor: wordAnchor.describe("The words it starts on, as an insert anchor: { startWord, endWord } or { quote, occurrence? }."),
+    cover_words: z.number().int().positive().max(10000).optional()
+        .describe("How many spoken words it stays on screen, counted from the first word of its anchor. Omitted means the anchored words only."),
+    enter: z.enum(LAYER_ENTERS).optional()
+        .describe("How it appears: cut (default), fade, slide (in from the nearest edge) or tilt_in. It leaves with a cut."),
+};
+/** Media drawn over the visible presenter at a fixed place; the presenter stays on screen and is billed. */
+export const ugcOverlay = z.object({
+    ...layerMedia,
+    position: z.enum(OVERLAY_POSITIONS).describe("A corner (top_left, top_right, bottom_left, bottom_right), or a band across the top or bottom."),
+}).strict().refine(hasOneSource, ONE_SOURCE);
+/** A reframing of the presenter: split shares a 9:16 frame with the media, card shows the media in a centred card. */
+export const ugcLayoutWindow = z.object({
+    ...layerMedia,
+    layout: z.enum(LAYOUT_WINDOW_KINDS).describe("split: presenter in the top half, media in the bottom half, captions on the seam (9:16 only). " +
+        "card: the media in a centred card over the presenter."),
+    blur_presenter: z.boolean().optional().describe("Card only: blur the presenter behind the card."),
+}).strict().refine(hasOneSource, ONE_SOURCE).refine(layout => layout.blur_presenter === undefined || layout.layout === "card", {
+    path: ["blur_presenter"], message: "blur_presenter works on a card window only",
 });
+/** A presenter size on its words (reference-elements S2): a hard cut in, settled over a few frames, back to the take at its end. */
+export const ugcFraming = z.object({
+    id: insertId.describe("Unique across inserts, overlays, layout_windows, templates and framing."),
+    anchor: layerMedia.anchor,
+    cover_words: z.number().int().positive().max(10000).optional()
+        .describe("How many spoken words the size holds, counted from the first word of its anchor. Omitted means the anchored words only."),
+    size: z.enum(FRAMING_SIZES).default("close").describe("close: the presenter 1.18 times larger about the face; medium: the take as rendered."),
+    transition: z.enum(FRAMING_TRANSITIONS).default("cut").describe("cut: a hard cut to the size; flash: a warm light leak over the cut."),
+}).strict();
+const templateEnvelope = {
+    id: insertId.describe("Unique across inserts, overlays, layout_windows and templates."),
+    anchor: layerMedia.anchor,
+    cover_words: layerMedia.cover_words,
+    placement: z.enum(TEMPLATE_PLACEMENTS).optional().describe("over (drawn over the presenter) or full (fills the frame); omitted means the " +
+        "kind's first placement, and a kind takes only the placements its catalog line names."),
+    transition: z.enum(INSERT_TRANSITIONS).optional().describe("Full placement only, as an insert's transition."),
+};
+const templateItem = (kind) => z.object({ ...templateEnvelope, kind: z.literal(kind.kind), data: kind.data }).strict();
+/** A graphic template (#778 S3): REST and the SDK take the strict union, `data` checked by `kind`. */
+export const ugcTemplate = z.discriminatedUnion("kind", [templateItem({ ...tag, kind: "tag" }),
+    templateItem({ ...lowerThird, kind: "lower_third" }), templateItem({ ...endCard, kind: "end_card" }),
+    templateItem({ ...titleCard, kind: "title_card" }), templateItem({ ...quote, kind: "quote" }), templateItem({ ...stat, kind: "stat" }),
+    templateItem({ ...callout, kind: "callout" }), templateItem({ ...checklist, kind: "checklist" }),
+    templateItem({ ...phoneCall, kind: "phone_call" }), templateItem({ ...compare, kind: "compare" }),
+    templateItem({ ...notification, kind: "notification" }), templateItem({ ...progress, kind: "progress" }),
+    templateItem({ ...rating, kind: "rating" })]);
+/** The slim MCP item: `data` is any object here, the catalog sits in the description and the server checks it strictly (D3). */
+export const mcpUgcTemplate = z.object({ ...templateEnvelope, kind: z.enum(TEMPLATE_KIND_IDS),
+    data: z.record(z.string(), z.unknown()).describe("The kind's fields, as its catalog line in templates names them.") }).strict();
+export const TEMPLATES_DESCRIPTION = templateCatalogText();
+const callVoice = z.string().regex(VOICE_NAME_PATTERN, "a call voice is a voice name from list_voices").optional();
+/** The call phone's measured place and rise (#914 D1e): the worker maps `rect_face` onto our presenter's face when it finds one, else uses `rect`. */
+export const callStage = z.strictObject({
+    rect: stagingRect.refine(rect => rect.width > 0 && rect.height > 0 && rect.left + rect.width <= 1 + 1e-6 && rect.top + rect.height <= 1 + 1e-6, "the phone's rect must lie inside the frame").describe("Where the phone settles, in shares of the frame."),
+    rect_face: stagingFaceRect.optional().describe("The same place relative to the presenter's face: origin the face centre, unit the face height."),
+    enter: z.strictObject({
+        from: z.enum(CALL_STAGE_SIDES),
+        displacement: z.tuple([z.number().min(-1).max(1), z.number().min(-1).max(1)]).describe("Settled minus first position, in shares of width and height."),
+        duration_s: z.number().min(0.1).max(CALL_STAGE_MAX_ENTER_SEC),
+        anchor: z.strictObject({ id: z.literal("freeze_start#1"), offset_s: z.number().min(-CALL_STAGE_MAX_LEAD_SEC).max(0) })
+            .describe("When the rise starts: seconds from the call's freeze, negative before it."),
+    }).optional(),
+    layer: z.enum(["behind_presenter"]).optional(),
+});
+/** A phone call after a quote (#857 S5): the presenter listens, then freezes, while the agent and the caller speak; then resumes. */
+export const ugcCall = z.strictObject({
+    after: wordAnchor.describe("The words the call follows: the presenter stops after the quote's last word and resumes on the next one."),
+    lines: z.array(z.strictObject({ speaker: z.enum(CALL_SPEAKERS),
+        text: z.string().min(1).max(MAX_CALL_LINE_CHARS).refine(text => text.trim().length > 0, "a call line needs words") }))
+        .min(2, "a call needs at least two lines").max(MAX_CALL_LINES)
+        .describe(`The call's turns in order, from both speakers; at most ${MAX_CALL_CHARS} characters and about ${MAX_CALL_SEC} s in all.`),
+    voices: z.strictObject({ agent: callVoice, caller: callVoice }).optional()
+        .describe(`Voice names from list_voices; omitted means ${DEFAULT_CALL_VOICES.agent} for the agent and ${DEFAULT_CALL_VOICES.caller} for the caller.`),
+    phone: z.strictObject({ caller: z.string().min(1).max(24).optional(), banner: z.string().min(1).max(32).optional(),
+        banner_note: z.string().min(1).max(48).optional(), mask_number: z.boolean().optional() }).optional()
+        .describe(`The in-call phone drawn over the call when no phone_call template covers it; omitted fields are ${CALL_PHONE_DEFAULTS.caller} ` +
+        `with its digits after the area code masked, "${CALL_PHONE_DEFAULTS.banner}" and "${CALL_PHONE_DEFAULTS.banner_note}".`),
+    stage: callStage.optional().describe("Where the in-call phone settles and how it rises, as a reference measured them (plan_reference_remake writes it); " +
+        "omitted is the reference call scene's own place and rise."),
+});
+/** The slim MCP call, which keeps tools/list under its ceiling: the server checks it strictly, as the template items (D3). */
+export const mcpUgcCall = z.record(z.string(), z.unknown())
+    .describe(`A call the presenter listens to: { after: { quote }, lines: [{ speaker: agent|caller, text }] (2–${MAX_CALL_LINES}), voices?, phone? }.`);
+/** What admission pins for an `asset_id` insert; the worker reads this key and checks this hash, never the asset row.
+ * Server-only: it lives at the top of the stored input, and a public body naming it is refused as an unknown field. */
+export const pinnedInsertAsset = z.object({
+    insert_id: insertId,
+    /** A template's media slot; ids refuse `.`, so `<id>.<slot>` keys never meet an overlay's (A1). */
+    slot: z.string().regex(/^[a-z][a-z_]{0,31}$/).optional(),
+    asset_id: assetId,
+    key: z.string().min(1).max(1024),
+    sha256: z.string().regex(/^[a-f0-9]{64}$/),
+    bytes: z.number().int().positive(),
+    kind: z.enum(ASSET_KINDS),
+    media_type: z.enum(ASSET_MEDIA_TYPES),
+    width: z.number().int().positive(),
+    height: z.number().int().positive(),
+    duration_frames: z.number().int().positive().optional(),
+    fps: z.number().int().positive().optional(),
+    codec: z.string().min(1).optional(),
+    pix_fmt: z.string().min(1).optional(),
+}).strict();
 /** Actor segment cap: a limit on ONE run, not on daily spend. */
 export const MAX_ACTOR_SEGMENTS = 3;
 export const MAX_SEGMENTS = 5;
@@ -130,13 +347,35 @@ export const makeUgcInputShape = {
     inserts: z.array(ugcInsert).min(1).max(MAX_INSERTS)
         .refine(inserts => new Set(inserts.map(insert => insert.id)).size === inserts.length, {
         message: "insert IDs must be unique",
-    }).optional().describe("Text-anchored image inserts over full narration, each covering cover_words spoken words from its anchor; " +
-        "requires long-form qualification on the server, captions=false, 1080p and explicit broll_policy=anyone."),
+    }).optional().describe("Text-anchored image or video inserts over full narration, each covering cover_words spoken words from its anchor; " +
+        "requires long-form qualification on the server, 1080p and explicit broll_policy=anyone. Captions draw over inserts."),
+    overlays: z.array(ugcOverlay).min(1).max(MAX_OVERLAYS).optional()
+        .describe("Text-anchored images or videos over the visible presenter, in a corner or a band at the top or bottom. At most 2 on screen at once, " +
+        "and two on screen together need positions that do not share a corner. Captions move to the middle or bottom third when an overlay " +
+        "meets them, never up over the face, and hide while neither is free. An overlay is not drawn while a full-frame insert is on screen. Same requirements as inserts: script, " +
+        "long-form qualification on the server, 1080p and explicit broll_policy=anyone. The presenter stays on screen, so the price does not change."),
+    layout_windows: z.array(ugcLayoutWindow).min(1).max(MAX_LAYOUT_WINDOWS).optional()
+        .describe("Text-anchored reframings of the presenter: split (9:16 only) or card. Windows may not overlap one another or an insert. " +
+        "Same requirements as inserts. A covered or blurred presenter is still delivered vendor work and is billed as face time."),
+    framing: z.array(ugcFraming).min(1).max(MAX_FRAMING).optional()
+        .describe("Text-anchored presenter sizes: each cuts to close or medium on its words and back to the take where they end. Items may not overlap " +
+        "one another, an insert or a layout window. A framing drawn wholly under full-frame templates is named in warnings[]. Where a punch_in " +
+        "emphasis meets a framing, the framing is drawn. Requires script and long-form qualification on the server; the price does not change."),
+    templates: z.array(ugcTemplate).min(1).max(MAX_TEMPLATES).optional().describe(TEMPLATES_DESCRIPTION),
+    template_theme: templateTheme.optional().describe("The look of every template in the run: a preset and an optional accent; only with templates."),
+    template_sounds: templateSounds.optional(),
+    edit_sounds: editSounds.optional(),
+    call: ugcCall.optional().describe("A phone call after a quote: the presenter listens, then freezes while the call plays as a phone line, " +
+        "with a ring first, and an in-call phone beside them shows it (a phone_call template covering the call is used instead). Needs script, " +
+        "a 9:16 frame and words after it. The frozen presenter and the call add production seconds, not presenter seconds, and a live-avatar " +
+        "still shown on the call has its own price in list_prices. Long-form qualification on the server."),
     person: z.string().min(1).max(500).optional(),
     actor_id: actorId
         .optional()
         .describe("Saved Clipwright actor ID from list_actors. Choose actor_id, image, or person; do not combine them. " +
         "Without voice or voice_id the voice follows the actor's gender. Do not combine with actor_gender."),
+    presenter_framing: z.enum(PRESENTER_FRAMINGS).optional().describe("close (default) or wide: presenter lower, room above. Needs the actor's wide view (list_actors), 9:16 only; else close plus warnings[]."),
+    presenter_mic: z.boolean().optional().describe("true: presenter holds a tiny mic. Needs the actor's mic view in that framing (list_actors; library ones are wide); else no mic plus warnings[]."),
     // https URLs only: the vendor takes URLs, and storage URLs are never passed to vendors,
     // so a `data:` URI is refused on input rather than accepted and dropped.
     image: z
@@ -162,8 +401,19 @@ export const makeUgcInputShape = {
     name: z.string().max(100).optional(),
     broll_url: z.string().url().max(MAX_URL_LENGTH).optional(),
     broll_policy: brollPolicy.optional(),
-    captions: z.boolean().default(false),
-    caption_style: z.enum(CAPTION_STYLES).default("hormozi"),
+    captions: z.boolean().default(false).describe("Burn word-timed captions into the video, over the presenter and over inserts. Not available with segments."),
+    caption_style: z.enum(CAPTION_STYLES).default("hormozi").describe(CAPTION_STYLE_DESCRIPTION),
+    caption_emphasis: z.array(captionEmphasisItem)
+        .min(1).max(MAX_CAPTION_EMPHASIS).optional().describe("Key words or short phrases to emphasise, each quoted from script and matched as an insert quote is (case and punctuation " +
+        "ignored). An item is the quote, or { quote, look }: look punch shows a small lead-in line from the same sentence over the " +
+        "quote as a large glowing keyword, look pill shows the quote alone in a rounded pill, look color shows it in the accent " +
+        "colour at the same size. Without a look, punch draws punch, hormozi and accent draw color, and other presets draw the quote larger " +
+        "in their highlight colour. Every occurrence is emphasised. Requires " +
+        "captions=true and script; a quote absent from script is refused before any charge."),
+    caption_mode: z.enum(CAPTION_MODES).optional().describe("full (default when omitted): every spoken word is captioned. highlights: captions appear only around caption_emphasis " +
+        "quotes (lead-in, quote, short tail) and nowhere else; requires caption_emphasis. In both modes captions are hidden while a " +
+        "full-frame insert is on screen or a template meets their band."),
+    caption_position: z.enum(CAPTION_POSITIONS).optional().describe("Where captions sit: top, middle, lower or bottom (80% of the height). Omitted means the caption_style's own place. Requires captions=true."),
     look: z.enum(LOOKS).default("natural"),
     // No .default(), so the resolver tells silence (snap with a warning) from an explicit
     // choice (refused on conflict). DEFAULT_ASPECT_RATIO (aspect.ts) fills it in.
@@ -205,18 +455,25 @@ export const makeUgcInputShape = {
         .enum(TTS_MODELS)
         .optional()
         .describe(`Speech model: ${TTS_MODELS.join(" | ")}. Omitted means the model of the chosen voice ` +
-        `(list_voices shows it): ${RUSSIAN_TTS_MODEL} for the Russian presets and for catalog voices named ru_*, ` +
-        `${MODEL_VOICE_MODEL} for its own voices, ` +
-        `${DEFAULT_TTS_MODEL} for every other preset and catalog voice. A raw voice_id speaks ${RUSSIAN_TTS_MODEL} ` +
-        `when the script is mostly Cyrillic and ${DEFAULT_TTS_MODEL} otherwise. An explicit tts_model always wins. ` +
-        `eleven_v4, eleven_v3 and ${GOOGLE_TTS_MODEL} read stress marks ` +
+        `(list_voices shows it): ${MODEL_VOICE_MODEL} for its own voices, ${DEFAULT_TTS_MODEL} for every preset, ` +
+        `catalog voice and raw voice_id. An explicit tts_model wins, except eleven_v3: it is no longer spoken, ` +
+        `and a run naming it speaks ${DEFAULT_TTS_MODEL} with a warning. ` +
+        `${DEFAULT_TTS_MODEL} and ${GOOGLE_TTS_MODEL} read stress marks ` +
         "(a capital vowel inside a Russian word, \"потОм\", becomes one; see script); " +
         "eleven_flash_v2_5 and eleven_turbo_v2_5 are cheaper alternatives for languages other than " +
         `Russian. ${GOOGLE_TTS_MODEL} speaks only its own voices (list_voices with model=${GOOGLE_TTS_MODEL}; without ` +
         `voice, ${MODEL_DEFAULT_VOICE_BY_GENDER.female} for a female actor and ${MODEL_DEFAULT_VOICE_BY_GENDER.male} otherwise) ` +
         "and returns no word timings: a preset or catalog voice, voice_id, captions=true, " +
-        "segments and inserts are refused with it before any charge. Audio tags in square brackets are an " +
-        "eleven_v3 and eleven_v4 convention and are not measured on it. " + SCRIPT_LENGTH_DESCRIPTION),
+        "segments and inserts are refused with it before any charge. Audio tags in square brackets are a " +
+        "convention of the other speech models and are not measured on it. " + SCRIPT_LENGTH_DESCRIPTION),
+    voice_pace: z
+        .number()
+        .min(VOICE_PACE_MIN)
+        .max(VOICE_PACE_MAX)
+        .optional()
+        .describe(`Narration speed; 1 is the voice's own. ${GOOGLE_TTS_MODEL} gets a style hint instead; ${DEFAULT_TTS_MODEL} has no speed, ` +
+        "so pick a voice by list_voices words_per_second; both named in warnings[]."),
+    pause_trim: pauseTrim.optional().describe("Shorten narration pauses longer than these seconds, cutting silence only."),
     webhook_url: z.string().url().max(MAX_URL_LENGTH).optional(),
     /** Removed visible label (clipwright#488). The key stays in the shape so that the refusal */
     /** names its reason instead of answering `unknown_field`. */
@@ -242,6 +499,63 @@ export const makeUgcInput = z
 })
     .refine(v => v.inserts === undefined || (v.script !== undefined && v.segments === undefined), {
     path: ["inserts"], message: "inserts requires script and cannot be combined with segments",
+})
+    .superRefine((v, context) => {
+    if (v.overlays === undefined && v.layout_windows === undefined)
+        return;
+    if (v.script === undefined || v.segments !== undefined) {
+        context.addIssue({ code: z.ZodIssueCode.custom, path: [v.overlays === undefined ? "layout_windows" : "overlays"],
+            message: "overlays and layout_windows require script and cannot be combined with segments" });
+        return;
+    }
+    for (const refusal of layerRefusals({ ...v, script: v.script }))
+        context.addIssue({ code: z.ZodIssueCode.custom, ...refusal });
+})
+    .superRefine((v, context) => {
+    if (v.framing === undefined)
+        return;
+    if (v.script === undefined || v.segments !== undefined) {
+        context.addIssue({ code: z.ZodIssueCode.custom, path: ["framing"], message: "framing requires script and cannot be combined with segments" });
+        return;
+    }
+    for (const refusal of framingRefusals({ ...v, script: v.script }))
+        context.addIssue({ code: z.ZodIssueCode.custom, ...refusal });
+})
+    // Template refusals sit in the schema, so REST, quote_ugc and MCP refuse alike before any hold (D4, A9).
+    .superRefine((v, context) => {
+    for (const refusal of [...templateRefusals(v), ...editSoundRefusals(v)])
+        context.addIssue({ code: z.ZodIssueCode.custom, ...refusal });
+})
+    .superRefine((v, context) => {
+    for (const refusal of callRefusals(v))
+        context.addIssue({ code: z.ZodIssueCode.custom, ...refusal });
+})
+    .refine(v => !v.captions || v.segments === undefined, {
+    path: ["captions"], message: "captions are not available with segments: pass script, with inserts for cutaways, or captions=false",
+})
+    .superRefine((v, context) => {
+    if (v.caption_mode === "highlights" && (!v.captions || v.caption_emphasis === undefined)) {
+        context.addIssue({ code: z.ZodIssueCode.custom, path: ["caption_mode"],
+            message: "caption_mode=highlights requires captions=true and caption_emphasis: highlights are drawn only around the quotes you emphasise" });
+    }
+    if (v.caption_position !== undefined && !v.captions) {
+        context.addIssue({ code: z.ZodIssueCode.custom, path: ["caption_position"], message: "caption_position requires captions=true: it places the burned captions" });
+    }
+    if (v.caption_emphasis === undefined)
+        return;
+    if (!v.captions || v.script === undefined) {
+        context.addIssue({ code: z.ZodIssueCode.custom, path: ["caption_emphasis"],
+            message: "caption_emphasis requires captions=true and script: it marks words of the burned captions" });
+        return;
+    }
+    const tokens = lexicalTokens(v.script);
+    for (const [index, item] of v.caption_emphasis.entries()) {
+        const { quote } = captionEmphasisOf(item);
+        if (quoteOccurrences(tokens, quote).length === 0) {
+            context.addIssue({ code: z.ZodIssueCode.custom, path: ["caption_emphasis", index],
+                message: `caption_emphasis "${quote}" does not occur in script: quote words exactly as the script spells them` });
+        }
+    }
 })
     .superRefine((v, context) => {
     for (const refusal of speechModelRefusals(v)) {
@@ -330,6 +644,14 @@ export function speechModelRefusals(input) {
             `segments are not available with ${model}: pass script for a single take, ${otherModel}`],
         ["inserts", input.inserts !== undefined,
             `inserts are not available with ${model}: it returns no word timings to anchor them; omit inserts, ${otherModel}`],
+        ["overlays", input.overlays !== undefined,
+            `overlays are not available with ${model}: it returns no word timings to anchor them; omit overlays, ${otherModel}`],
+        ["layout_windows", input.layout_windows !== undefined,
+            `layout_windows are not available with ${model}: it returns no word timings to anchor them; omit layout_windows, ${otherModel}`],
+        ["framing", input.framing !== undefined,
+            `framing is not available with ${model}: it returns no word timings to anchor it; omit framing, ${otherModel}`],
+        ["call", input.call !== undefined,
+            `call is not available with ${model}: it returns no word timings to open the call after its quote; omit call, ${otherModel}`],
     ];
     return candidates.filter(([, refused]) => refused).map(([field, , message]) => ({ field, message }));
 }
@@ -340,6 +662,15 @@ export function serverUgcInputWith(voiceRefusal) {
         .refine((v) => v.voice === undefined || voiceRefusal(v.voice) === undefined, {
         path: ["voice"],
         error: (issue) => voiceRefusal(issue.input.voice),
+    })
+        // A call speaks ElevenLabs catalog voices only: a model's own voice has no dialogue.
+        .superRefine((v, context) => {
+        for (const speaker of CALL_SPEAKERS) {
+            const name = v.call?.voices?.[speaker];
+            const why = name === undefined ? undefined : isModelVoiceName(name) ? `"${name}" is a voice of ${MODEL_VOICE_MODEL}, which speaks no call` : voiceRefusal(name);
+            if (why)
+                context.addIssue({ code: z.ZodIssueCode.custom, path: ["call", "voices", speaker], message: why });
+        }
     })
         // The cap the client skipped: the server knows the model of an admitted catalog voice.
         .refine((v) => !modelUnknownToClient(v) ||
@@ -350,12 +681,26 @@ export function serverUgcInputWith(voiceRefusal) {
     });
 }
 /** A stored run input already passed admission; a model or cap change must not make an */
-/** old run unreadable. The snapshot keeps the actor's gender. */
+/** old run unreadable. The snapshot keeps the actor's gender: the parse feeds the timeline digest, so it stays this narrow. */
 export const storedUgcInput = z.object({
     ...makeUgcInputShape,
     tts_model: z.string().optional(),
     actor_snapshot: z.object({ gender: z.enum(["female", "male"]).optional() }).optional(),
+    insert_assets: z.array(pinnedInsertAsset).min(1).max(MAX_INSERTS + MAX_OVERLAYS + MAX_LAYOUT_WINDOWS + MAX_TEMPLATE_MEDIA).optional(),
+    composition_version: z.literal(UGC_COMPOSITION_VERSION).optional(),
+    /** The model admission resolved; absent on runs admitted before 2026-10-25. */
+    resolved_tts_model: z.string().optional(),
 });
+/** Whether a run takes the narrated long-form path: one script with inserts, overlays, layout windows, framing or a call. */
+export function isNarratedUgcInput(input) {
+    return input.segments === undefined && (input.inserts !== undefined || input.overlays !== undefined || input.layout_windows !== undefined ||
+        input.framing !== undefined || input.call !== undefined);
+}
+/** The pinned asset of an `asset_id` insert, overlay, layout window or template slot in a stored input; a public input has none. */
+export function pinnedInsertAssetOf(input, insertId, slot) {
+    const pinned = input.insert_assets;
+    return pinned?.find(asset => asset.insert_id === insertId && asset.slot === slot);
+}
 /** What the worker voices apart: the script, or each actor segment's line. */
 function spokenUnitsOf(input) {
     if (input.script !== undefined)
@@ -379,8 +724,18 @@ export function resolvedScript(input) {
 }
 // The INPUT type (`MakeUgcInputArgs`) lives in `contract-dispositions.ts`: it comes from the
 // OFFERED shape, so SDK autocomplete does not show rejected fields.
+/** A plain run's tariff before parts-v1 (#800): 30 credits per second of finished video, known by the absence of `run_billing_terms` (#840 D2). */
+export const UGC_PER_SECOND_TARIFF = "ugc-per-second-v1";
+/** That tariff's rate (docs/06): runs admitted before parts-v1 settle at it; service-core rounds the duration up before multiplying. */
+export const CREDITS_PER_SECOND = 30;
 export const quoteResponse = z.object({
     long_form_pricing: longFormQuoteSchema.optional(),
+    /** The tariff the run is admitted at: `ugc-per-second-v1`, or long form's `pricingVersion` (#840 D3). A string, not an enum: a */
+    /** tariff the client does not know yet must not break `quote`; optional, so a quote stored before it still reads. */
+    tariff: z.string().min(1).max(200).optional(),
+    /** The estimate by part (#800): presenter seconds by engine, production seconds, live-avatar stills; the minimum applies after. */
+    price_lines: z.array(partsLineSchema).optional(),
+    minimum_credits: z.number().int().nonnegative().optional(),
     skill: z.string(),
     credits_estimate: z.number().int().nonnegative(),
     duration_estimate_sec: z.number().positive(),