@clipwright/core 0.18.0 → 0.20.0

package/dist/skills.d.ts

@@ -1,80 +1,36 @@
 import { z } from "zod";
 export declare const CAPTION_STYLES: readonly ["hormozi", "tiktok", "minimal"];
 export declare const LOOKS: readonly ["natural", "commercial", "raw_iphone"];
-/**
- * Публичное множество форматов = ИЗМЕРЕННОЕ множество, а не вендорская дока.
- *
- * Вендор принимает шесть форматов, но живьём у нас проверены два, и ровно эти
- * два объявляет `CAPABILITIES` адаптера. Объявить в схеме больше — значит
- * принять значение, которое пайплайн потом отклонит; это тот самый класс
- * расхождения, ради устранения которого пересматривается контракт. Расширение —
- * отдельное стори (US-535) и только после живого измерения (US-530).
- */
+/** Public formats = formats MEASURED live, not the vendor docs: declaring more would */
+/** accept values the pipeline later rejects. */
 export declare const ASPECT_RATIOS: readonly ["9:16", "1:1", "16:9"];
 export type AspectRatio = (typeof ASPECT_RATIOS)[number];
-/**
- * Разрешение выхода. Значения — те, что реально принимает HeyGen v3
- * (проверено 18.07.2026: `480p` и ниже отклоняются с
- * `Input should be '4k', '1080p' or '720p'`).
- *
- * Фактические кадры при `aspect_ratio: "9:16"` — замерены на реальных файлах:
- *   720p  → 720 × 1280   (~590 КБ на 7 сек)
- *   1080p → 1080 × 1920  (~923 КБ)
- *   4k    → 2160 × 3840  (~3.7 МБ)
- *
- * ВАЖНО: на стоимость разрешение НЕ влияет. HeyGen тарифицирует по
- * длительности (~1 кредит/сек): все три варианта стоили одинаково — 8
- * кредитов за один и тот же 7.36-секундный ролик. Понижать разрешение ради
- * экономии кредитов бессмысленно; экономят короткие скрипты и фикстурный
- * режим. 720p в деве берётся ради скорости скачивания и объёма в R2
- * (файл в 6 раз меньше 4k), а не ради денег.
- */
+/** Output resolution, as the vendor accepts it (720p: 720×1280, 1080p: 1080×1920, 4k: 2160×3840 */
+/** at 9:16). Resolution does not change the price; dev uses 720p for download size only. */
 export declare const RESOLUTIONS: readonly ["720p", "1080p", "4k"];
 export type Resolution = (typeof RESOLUTIONS)[number];
-/**
- * Продуктовый дефолт — 1080p, и это не деталь реализации.
- * Конкурент обещает 1080p, а отдаёт 720p (docs/08); наше обещание держать
- * 1080×1920 — заявленный дифференциатор и правило проекта №4. Понижение
- * дефолта допустимо ТОЛЬКО в dev-окружении, где ролики никто не публикует.
- */
+/** The 1080×1920 default is a product promise; only dev, where nothing is published, */
+/** may lower it. */
 export declare const DEFAULT_RESOLUTION: Resolution;
 export declare const DEV_RESOLUTION: Resolution;
-/**
- * Разрешение конкретного рана: явный выбор клиента важнее любых дефолтов,
- * иначе dev-окружение молча подменяло бы то, что пользователь запросил.
- */
+/** Resolution of a run: an explicit client choice beats any default, or dev would */
+/** silently replace what the user asked for. */
 export declare function resolveResolution(requested: Resolution | undefined, isDev: boolean): Resolution;
-/** Потолок длины ЛЮБОГО адреса из чужого тела: без него поле берёт весь потолок */
-/** тела запроса. Число — верхний предел, который переваривает любой браузер и CDN. */
+/** Length cap for ANY URL from a foreign body; without it the field takes the whole */
+/** body cap. The value is the upper bound any browser and CDN handles. */
 export declare const MAX_URL_LENGTH = 2048;
-/** Скиллы общего неймспейса ранов. Колонка `runs.skill` — текст, поэтому читается через `parseSkill`. */
+/** Skills in the shared run namespace. `runs.skill` is text, so it is read through `parseSkill`. */
 export declare const SKILLS: readonly ["make_ugc", "create_actor"];
 export type Skill = (typeof SKILLS)[number];
 export declare function parseSkill(value: unknown): Skill | null;
-/** ЧТО ДЕЛАЕТ `make_ugc` — один текст на обе контрактные поверхности: публичный */
-/** REST-каталог и MCP `tools/list`. Разойдясь, они описали бы РАЗНЫЙ скилл. */
+/** What `make_ugc` does: one text for both contract surfaces, the public REST catalog */
+/** and MCP `tools/list`, so they never describe different skills. */
 export declare const MAKE_UGC_DESCRIPTION: string;
-/** Как ЗВАТЬ скилл по MCP. Отдельно от описания выше: имена соседних тулов и */
-/** поллинг — свойства протокола, и REST-каталогу они не адресованы. */
+/** How to CALL the skill over MCP. Kept apart from the description: neighboring tool */
+/** names and polling are protocol details not meant for the REST catalog. */
 export declare const MAKE_UGC_AGENT_PROTOCOL: string;
-/**
- * Сырой zod-shape входа make_ugc — БЕЗ `.refine()`.
- *
- * ЗАЧЕМ ОТДЕЛЬНО ОТ `makeUgcInput`: `makeUgcInput` после `.refine()` становится
- * `ZodEffects`, у которого НЕТ `.shape` (ловушка A12). MCP-тул (`tools/list`) и
- * прочие потребители, которым нужен именно объект полей, обязаны собираться из
- * этого shape, а не переписывать поля руками (правило проекта №2 — не дублировать
- * схему). `makeUgcInput` пересобирается из ЭТОГО ЖЕ shape ниже, чтобы они не
- * разошлись.
- */
-/**
- * Один сегмент ролика. Форма объявляется ЗДЕСЬ, в Slice 1, хотя реализация —
- * в Slice 2 (US-526): поле `segments` требует `script → .optional()`, а это
- * меняет `required[]` в `tools/list`. Приедь правка позже, публичная форма
- * сменилась бы ПОСЛЕ проверки вторым пользователем и обесценила бы её —
- * единственную внешне фальсифицируемую проверку продукта. Здесь required-набор
- * меняется один раз, до гейта, а Slice 2 сводится к снятию строки отказа.
- */
+/** 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 declare const ugcSegment: z.ZodObject<{
     kind: z.ZodEnum<{
         actor: "actor";
@@ -120,11 +76,11 @@ export declare const ugcInsert: z.ZodObject<{
     }, z.core.$strict>>;
 }, z.core.$strict>;
 export type UgcInsert = z.infer<typeof ugcInsert>;
-/** Потолок актёрских сегментов — ограничение ОДНОГО рана, не суточных трат. */
+/** Actor segment cap: a limit on ONE run, not on daily spend. */
 export declare const MAX_ACTOR_SEGMENTS = 3;
 export declare const MAX_SEGMENTS = 5;
-/** Потолки НАРРАТИВНОГО пути — другие, потому что медиа-шот денег не стоит, */
-/** а актёрский стоит: вставок столько, сколько вмещает таймлайн (ADR #265). */
+/** Narrated-path caps differ because a media shot costs nothing and an actor shot does: */
+/** as many inserts as the timeline holds. */
 export declare const MAX_INSERTS: number;
 export declare const MAX_NARRATED_ACTOR_SHOTS = 6;
 export declare const actorId: z.ZodString;
@@ -217,39 +173,19 @@ export declare const makeUgcInputShape: {
         eleven_v3: "eleven_v3";
     }>>;
     readonly webhook_url: z.ZodOptional<z.ZodString>;
-    /**
-     * Видимая плашка «сделано ИИ» поверх кадра — OPT-IN, а не обязательная.
-     *
-     * Обязательный вотермарк отменил бы заявленный дифференциатор («без
-     * вотермарки»), поэтому раскрытие держится на контрактных полях и на теге
-     * внутри файла, а плашка остаётся выбором вызывателя. Выжигание её в кадр
-     * требует композиции: она появилась в US-527, и US-539 перевёл поле в
-     * `implemented` (обусловлено флагом `CLIPWRIGHT_COMPOSE`).
-     */
+    /** Visible "made with AI" overlay, OPT-IN: disclosure rests on contract fields and file */
+    /** metadata. Burning it in needs composition (gated by `CLIPWRIGHT_COMPOSE`). */
     readonly disclosure_overlay: z.ZodOptional<z.ZodBoolean>;
-    /**
-     * Чем заполнять кадр, когда клип не покрывает его целиком (US-527).
-     *
-     * БЕЗ `.default()` НАМЕРЕННО. Дефолт здесь означал бы, что мы выбираем за
-     * клиента, как выглядит его ролик там, где формат не совпал с источником, —
-     * и выбираем МОЛЧА. Отсутствие поля значит «укладки не требуется»; если она
-     * всё же понадобилась, ран обязан сказать об этом в `warnings[]`, а не
-     * подобрать фон по своему вкусу.
-     *
-     * `contain` — вписать целиком (поля видны), `white` — белые поля как у
-     * вендора, `blur` — размытая заливка тем же кадром.
-     */
+    /** How to fill a frame the clip does not cover. No `.default()`: absence means no layout */
+    /** is needed. `contain` fits whole, `white` pads white, `blur` fills with the blurred frame. */
     readonly background: z.ZodOptional<z.ZodEnum<{
         blur: "blur";
         contain: "contain";
         white: "white";
     }>>;
 };
-/**
- * Ретрай-параметр агентного скилла: НОМЕР попытки. Живёт в core (не рукописно в
- * MCP и CLI сразу), но ОТДЕЛЬНО от `makeUgcInputShape` — это вход СКИЛЛА
- * (порождает суффикс `:N` у ключа идемпотентности в SDK), а не параметр рендера.
- */
+/** Agent retry parameter: the attempt NUMBER. Kept apart from `makeUgcInputShape` because it */
+/** is a skill input (the `:N` idempotency-key suffix in the SDK), not a render parameter. */
 export declare const agentRetryShape: {
     readonly attempt: z.ZodOptional<z.ZodNumber>;
 };
@@ -349,8 +285,8 @@ export declare const makeUgcInput: z.ZodObject<{
         white: "white";
     }>>;
 }, z.core.$strip>;
-/** Вход API: имя голоса сверяет `voiceRefusal` сервера. Каталог сюда не импортируется — */
-/** баррел читают клиенты; сервер берёт готовую схему из `@clipwright/core/voice-admission`. */
+/** API input: the server's `voiceRefusal` checks the voice name. The catalog is not imported */
+/** here, since clients read this barrel; the server uses `@clipwright/core/voice-admission`. */
 export declare function serverUgcInputWith(voiceRefusal: (voice: string) => string | undefined): z.ZodObject<{
     script: z.ZodOptional<z.ZodString>;
     segments: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -447,8 +383,8 @@ export declare function serverUgcInputWith(voiceRefusal: (voice: string) => stri
         white: "white";
     }>>;
 }, z.core.$strip>;
-/** Сохранённый вход рана: правила допуска он уже прошёл, и смена модели или */
-/** потолка не должна делать старый ран нечитаемым (#145). Снимок — ради пола (#210). */
+/** 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. */
 export declare const storedUgcInput: z.ZodObject<{
     script: z.ZodOptional<z.ZodString>;
     segments: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -547,23 +483,13 @@ export declare const storedUgcInput: z.ZodObject<{
         }>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
-/** Минимум, из которого выводится произносимый текст: сам скрипт или сегменты. */
+/** The minimum the spoken text is derived from: the script itself or the segments. */
 export interface SpokenTextInput {
     script?: string | undefined;
     segments?: readonly UgcSegment[] | undefined;
 }
-/**
- * ЕДИНСТВЕННОЕ место, где «`script` либо сам, либо склейка сегментов»
- * превращается в `string`.
- *
- * ЗАЧЕМ ХЕЛПЕР, А НЕ `!` НА СЕМИ CALL-SITE'АХ. Снятие обязательности со
- * `script` делает его `string | undefined` у каждого потребителя, и `.refine`
- * спасает в рантайме, а компилятор — нет. Самый чувствительный из них —
- * `elevenlabs-tts.ts`, где комментарий прямо опирался на `z.string().min(1)`
- * как на ГАРД ПЕРЕД ПЛАТНЫМ POST: заткни мы там типы, гард остался бы снятым,
- * а компилятор бы об этом молчал. Поэтому проверка непустоты живёт ВНУТРИ
- * хелпера и восстанавливает гард явно, а не полагается на снятую схему.
- */
+/** The ONLY place where "script or joined segments" becomes a `string`. The non-empty */
+/** check lives here, restoring the guard before the paid TTS call that the schema no longer holds. */
 export declare function resolvedScript(input: SpokenTextInput): string;
 export type MakeUgcInput = z.infer<typeof makeUgcInput>;
 export declare const quoteResponse: z.ZodObject<{