@clipwright/core 0.1.0

package/dist/skills.d.ts

@@ -0,0 +1,270 @@
+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).
+ */
+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), а не ради денег.
+ */
+export declare const RESOLUTIONS: readonly ["720p", "1080p", "4k"];
+export type Resolution = (typeof RESOLUTIONS)[number];
+/**
+ * Продуктовый дефолт — 1080p, и это не деталь реализации.
+ * Конкурент обещает 1080p, а отдаёт 720p (docs/08); наше обещание держать
+ * 1080×1920 — заявленный дифференциатор и правило проекта №4. Понижение
+ * дефолта допустимо ТОЛЬКО в dev-окружении, где ролики никто не публикует.
+ */
+export declare const DEFAULT_RESOLUTION: Resolution;
+export declare const DEV_RESOLUTION: Resolution;
+/**
+ * Разрешение конкретного рана: явный выбор клиента важнее любых дефолтов,
+ * иначе dev-окружение молча подменяло бы то, что пользователь запросил.
+ */
+export declare function resolveResolution(requested: Resolution | undefined, isDev: boolean): Resolution;
+/**
+ * Потолок длины скрипта (docs/12 §11, ~45с озвучки) — временная замена
+ * мульти-тейка (docs/12 §3: длинные скрипты раньше резались на несколько
+ * тейков, эта логика вырезана на время прототипа). Пока мульти-тейк не
+ * вернули, скрипт длиннее одного тейка нужно отклонять на входе, а не
+ * молча обрезать или рендерить с нарушением пейсинг-гейта.
+ *
+ * Число слов считаем от ВЕРХНЕЙ границы пейсинга (WORDS_PER_SECOND_MAX из
+ * pacing.ts) — это самый длинный скрипт, который ещё способен уложиться в
+ * потолок секунд без нарушения пейсинг-гейта. Числа пейсинга не дублируем,
+ * берём готовые константы из pacing.ts.
+ */
+export declare const MAX_SCRIPT_SECONDS = 45;
+export declare const MAX_SCRIPT_WORDS: number;
+/**
+ * Сырой 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 сводится к снятию строки отказа.
+ */
+export declare const ugcSegment: z.ZodObject<{
+    kind: z.ZodEnum<{
+        actor: "actor";
+        media: "media";
+    }>;
+    script: z.ZodOptional<z.ZodString>;
+    media_url: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type UgcSegment = z.infer<typeof ugcSegment>;
+/** Потолок актёрских сегментов — ограничение ОДНОГО рана, не суточных трат. */
+export declare const MAX_ACTOR_SEGMENTS = 3;
+export declare const MAX_SEGMENTS = 5;
+export declare const makeUgcInputShape: {
+    readonly script: z.ZodOptional<z.ZodString>;
+    readonly segments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            actor: "actor";
+            media: "media";
+        }>;
+        script: z.ZodOptional<z.ZodString>;
+        media_url: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    readonly person: z.ZodOptional<z.ZodString>;
+    readonly image: z.ZodOptional<z.ZodString>;
+    readonly character: z.ZodOptional<z.ZodString>;
+    readonly name: z.ZodOptional<z.ZodString>;
+    readonly broll_url: z.ZodOptional<z.ZodString>;
+    readonly captions: z.ZodDefault<z.ZodBoolean>;
+    readonly caption_style: z.ZodDefault<z.ZodEnum<{
+        hormozi: "hormozi";
+        minimal: "minimal";
+        tiktok: "tiktok";
+    }>>;
+    readonly look: z.ZodDefault<z.ZodEnum<{
+        commercial: "commercial";
+        natural: "natural";
+        raw_iphone: "raw_iphone";
+    }>>;
+    readonly aspect_ratio: z.ZodOptional<z.ZodEnum<{
+        "16:9": "16:9";
+        "1:1": "1:1";
+        "9:16": "9:16";
+    }>>;
+    readonly resolution: z.ZodOptional<z.ZodEnum<{
+        "1080p": "1080p";
+        "4k": "4k";
+        "720p": "720p";
+    }>>;
+    readonly voice: z.ZodOptional<z.ZodEnum<{
+        daria_ru_female: "daria_ru_female";
+        eric: "eric";
+        george: "george";
+        owner_ru_clone: "owner_ru_clone";
+        sarah: "sarah";
+    }>>;
+    readonly voice_id: z.ZodOptional<z.ZodString>;
+    readonly webhook_url: z.ZodOptional<z.ZodString>;
+    /**
+     * Видимая плашка «сделано ИИ» поверх кадра — OPT-IN, а не обязательная.
+     *
+     * Обязательный вотермарк отменил бы заявленный дифференциатор («без
+     * вотермарки»), поэтому раскрытие держится на контрактных полях и на теге
+     * внутри файла, а плашка остаётся выбором вызывателя. Выжигание её в кадр
+     * требует композиции: она появилась в US-527, и US-539 перевёл поле в
+     * `implemented` (обусловлено флагом `CLIPWRIGHT_COMPOSE`).
+     */
+    readonly disclosure_overlay: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * Чем заполнять кадр, когда клип не покрывает его целиком (US-527).
+     *
+     * БЕЗ `.default()` НАМЕРЕННО. Дефолт здесь означал бы, что мы выбираем за
+     * клиента, как выглядит его ролик там, где формат не совпал с источником, —
+     * и выбираем МОЛЧА. Отсутствие поля значит «укладки не требуется»; если она
+     * всё же понадобилась, ран обязан сказать об этом в `warnings[]`, а не
+     * подобрать фон по своему вкусу.
+     *
+     * `contain` — вписать целиком (поля видны), `white` — белые поля как у
+     * вендора, `blur` — размытая заливка тем же кадром.
+     */
+    readonly background: z.ZodOptional<z.ZodEnum<{
+        blur: "blur";
+        contain: "contain";
+        white: "white";
+    }>>;
+};
+/**
+ * Ретрай-параметр агентного скилла: НОМЕР попытки. Живёт в core (не рукописно в
+ * MCP и CLI сразу), но ОТДЕЛЬНО от `makeUgcInputShape` — это вход СКИЛЛА
+ * (порождает суффикс `:N` у ключа идемпотентности в SDK), а не параметр рендера.
+ */
+export declare const agentRetryShape: {
+    readonly attempt: z.ZodOptional<z.ZodNumber>;
+};
+/**
+ * Вход make_ugc. Не более одного из person | image задаёт идентичность (оба
+ * опущены → дефолтный актёр). Схема — единый источник правды для REST, MCP
+ * (tools/list) и SDK.
+ *
+ * `character` из взаимоисключения ВЫВЕДЕН, а не забыт: его диспозиция —
+ * `rejected` (`contract-dispositions.ts`), то есть поле отбивается на входе
+ * раньше, чем дойдёт до этой проверки. Держать его здесь значило бы
+ * валидировать выбор между вариантами, один из которых не существует.
+ */
+export declare const makeUgcInput: z.ZodObject<{
+    script: z.ZodOptional<z.ZodString>;
+    segments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            actor: "actor";
+            media: "media";
+        }>;
+        script: z.ZodOptional<z.ZodString>;
+        media_url: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    person: z.ZodOptional<z.ZodString>;
+    image: z.ZodOptional<z.ZodString>;
+    character: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+    broll_url: z.ZodOptional<z.ZodString>;
+    captions: z.ZodDefault<z.ZodBoolean>;
+    caption_style: z.ZodDefault<z.ZodEnum<{
+        hormozi: "hormozi";
+        minimal: "minimal";
+        tiktok: "tiktok";
+    }>>;
+    look: z.ZodDefault<z.ZodEnum<{
+        commercial: "commercial";
+        natural: "natural";
+        raw_iphone: "raw_iphone";
+    }>>;
+    aspect_ratio: z.ZodOptional<z.ZodEnum<{
+        "16:9": "16:9";
+        "1:1": "1:1";
+        "9:16": "9:16";
+    }>>;
+    resolution: z.ZodOptional<z.ZodEnum<{
+        "1080p": "1080p";
+        "4k": "4k";
+        "720p": "720p";
+    }>>;
+    voice: z.ZodOptional<z.ZodEnum<{
+        daria_ru_female: "daria_ru_female";
+        eric: "eric";
+        george: "george";
+        owner_ru_clone: "owner_ru_clone";
+        sarah: "sarah";
+    }>>;
+    voice_id: z.ZodOptional<z.ZodString>;
+    webhook_url: z.ZodOptional<z.ZodString>;
+    disclosure_overlay: z.ZodOptional<z.ZodBoolean>;
+    background: z.ZodOptional<z.ZodEnum<{
+        blur: "blur";
+        contain: "contain";
+        white: "white";
+    }>>;
+}, z.core.$strip>;
+/** Минимум, из которого выводится произносимый текст: сам скрипт или сегменты. */
+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: заткни мы там типы, гард остался бы снятым,
+ * а компилятор бы об этом молчал. Поэтому проверка непустоты живёт ВНУТРИ
+ * хелпера и восстанавливает гард явно, а не полагается на снятую схему.
+ */
+export declare function resolvedScript(input: SpokenTextInput): string;
+export type MakeUgcInput = z.infer<typeof makeUgcInput>;
+export declare const quoteResponse: z.ZodObject<{
+    skill: z.ZodString;
+    credits_estimate: z.ZodNumber;
+    duration_estimate_sec: z.ZodNumber;
+    warnings: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    contract_version: z.ZodString;
+    source: z.ZodNullable<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        aspect_ratio: z.ZodString;
+    }, z.core.$strip>>;
+    resolved_aspect_ratio: z.ZodEnum<{
+        "16:9": "16:9";
+        "1:1": "1:1";
+        "9:16": "9:16";
+    }>;
+}, z.core.$strip>;
+export type QuoteResponse = z.infer<typeof quoteResponse>;

package/dist/skills.js

@@ -0,0 +1,291 @@
+import { z } from "zod";
+import { WORDS_PER_SECOND_MAX, countWords } from "./pacing.js";
+import { VOICE_ID_PATTERN, VOICE_PRESET_NAMES } from "./voices.js";
+export const CAPTION_STYLES = ["hormozi", "tiktok", "minimal"];
+export const LOOKS = ["natural", "commercial", "raw_iphone"];
+/**
+ * Публичное множество форматов = ИЗМЕРЕННОЕ множество, а не вендорская дока.
+ *
+ * Вендор принимает шесть форматов, но живьём у нас проверены два, и ровно эти
+ * два объявляет `CAPABILITIES` адаптера. Объявить в схеме больше — значит
+ * принять значение, которое пайплайн потом отклонит; это тот самый класс
+ * расхождения, ради устранения которого пересматривается контракт. Расширение —
+ * отдельное стори (US-535) и только после живого измерения (US-530).
+ */
+export const ASPECT_RATIOS = ["9:16", "1:1", "16:9"];
+/**
+ * Разрешение выхода. Значения — те, что реально принимает 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), а не ради денег.
+ */
+export const RESOLUTIONS = ["720p", "1080p", "4k"];
+/**
+ * Продуктовый дефолт — 1080p, и это не деталь реализации.
+ * Конкурент обещает 1080p, а отдаёт 720p (docs/08); наше обещание держать
+ * 1080×1920 — заявленный дифференциатор и правило проекта №4. Понижение
+ * дефолта допустимо ТОЛЬКО в dev-окружении, где ролики никто не публикует.
+ */
+export const DEFAULT_RESOLUTION = "1080p";
+export const DEV_RESOLUTION = "720p";
+/**
+ * Разрешение конкретного рана: явный выбор клиента важнее любых дефолтов,
+ * иначе dev-окружение молча подменяло бы то, что пользователь запросил.
+ */
+export function resolveResolution(requested, isDev) {
+    if (requested)
+        return requested;
+    return isDev ? DEV_RESOLUTION : DEFAULT_RESOLUTION;
+}
+/**
+ * Потолок длины скрипта (docs/12 §11, ~45с озвучки) — временная замена
+ * мульти-тейка (docs/12 §3: длинные скрипты раньше резались на несколько
+ * тейков, эта логика вырезана на время прототипа). Пока мульти-тейк не
+ * вернули, скрипт длиннее одного тейка нужно отклонять на входе, а не
+ * молча обрезать или рендерить с нарушением пейсинг-гейта.
+ *
+ * Число слов считаем от ВЕРХНЕЙ границы пейсинга (WORDS_PER_SECOND_MAX из
+ * pacing.ts) — это самый длинный скрипт, который ещё способен уложиться в
+ * потолок секунд без нарушения пейсинг-гейта. Числа пейсинга не дублируем,
+ * берём готовые константы из pacing.ts.
+ */
+export const MAX_SCRIPT_SECONDS = 45;
+export const MAX_SCRIPT_WORDS = MAX_SCRIPT_SECONDS * WORDS_PER_SECOND_MAX;
+/**
+ * Сырой 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 сводится к снятию строки отказа.
+ */
+export const ugcSegment = z.object({
+    kind: z.enum(["actor", "media"]),
+    /** Реплика актёра. У `media`-сегмента отсутствует — там говорит соседний актёр. */
+    script: z.string().min(1).max(10_000).optional(),
+    /** Полнокадровый врез. Обязателен у `media`, запрещён у `actor`. */
+    media_url: z.string().url().optional(),
+});
+/** Потолок актёрских сегментов — ограничение ОДНОГО рана, не суточных трат. */
+export const MAX_ACTOR_SEGMENTS = 3;
+export const MAX_SEGMENTS = 5;
+export const makeUgcInputShape = {
+    // НЕОБЯЗАТЕЛЬНЫЙ, но не «необязательный к заполнению»: ровно одно из
+    // `script | segments` обязано присутствовать, и это держит `.refine` ниже.
+    // JSON-Schema не умеет выразить «ровно одно из двух» через `required[]`,
+    // поэтому информативность возвращается текстом описания (блокер B9).
+    script: z
+        .string()
+        .min(1)
+        .max(10_000)
+        .optional()
+        .describe("required unless `segments` is provided; `segments` is currently rejected"),
+    segments: z.array(ugcSegment).min(1).max(MAX_SEGMENTS).optional(),
+    person: z.string().min(1).max(500).optional(),
+    // ТОЛЬКО https-URL. Вариант `data:` снят (US-524): HeyGen принимает
+    // исключительно `{type:"url"}`, а заливка data-URI в R2 с presigned-выдачей
+    // вскрыла бы инвариант Этапа 4 «R2-URL вендору не передаются». Отказ на входе
+    // честнее, чем приём поля, которое некуда деть.
+    image: z.string().url().startsWith("https://").optional(),
+    character: z.string().regex(/^char_[a-zA-Z0-9]+$/).optional(),
+    name: z.string().max(100).optional(),
+    broll_url: z.string().url().optional(),
+    captions: z.boolean().default(false),
+    caption_style: z.enum(CAPTION_STYLES).default("hormozi"),
+    look: z.enum(LOOKS).default("natural"),
+    // Намеренно БЕЗ .default() — по той же причине, что и resolution ниже, но с
+    // ПРОДУКТОВЫМ следствием: дефолт здесь означал бы «клиент всегда просит
+    // 9:16», и резолвер формата не смог бы отличить молчание от явного выбора.
+    // На этом различии стоит вся развилка: промолчал — снап к формату источника с
+    // предупреждением, попросил явно и не сходится — отказ до платного вызова.
+    // Дефолт подставляет DEFAULT_ASPECT_RATIO (aspect.ts).
+    aspect_ratio: z.enum(ASPECT_RATIOS).optional(),
+    // Намеренно БЕЗ .default(): отличить «клиент попросил 1080p» от «клиент
+    // промолчал» можно только так. Дефолт подставляет resolveResolution(),
+    // потому что он зависит от окружения, а схема о нём знать не должна.
+    resolution: z.enum(RESOLUTIONS).optional(),
+    // Оба голосовых поля — .optional() БЕЗ .default() по той же причине, что и
+    // resolution выше: отличить «клиент явно выбрал голос» от «клиент промолчал»
+    // можно только так. Дефолт (клон владельца) подставляет резолвер в адаптере,
+    // а не схема; явность нужна тестам warnings (US-517). voice — наше имя пресета
+    // (enum порождает tools/list), voice_id — сырой вендорский id как escape hatch.
+    voice: z.enum(VOICE_PRESET_NAMES).optional(),
+    voice_id: z.string().regex(VOICE_ID_PATTERN).optional(),
+    webhook_url: z.string().url().optional(),
+    /**
+     * Видимая плашка «сделано ИИ» поверх кадра — OPT-IN, а не обязательная.
+     *
+     * Обязательный вотермарк отменил бы заявленный дифференциатор («без
+     * вотермарки»), поэтому раскрытие держится на контрактных полях и на теге
+     * внутри файла, а плашка остаётся выбором вызывателя. Выжигание её в кадр
+     * требует композиции: она появилась в US-527, и US-539 перевёл поле в
+     * `implemented` (обусловлено флагом `CLIPWRIGHT_COMPOSE`).
+     */
+    disclosure_overlay: z.boolean().optional(),
+    /**
+     * Чем заполнять кадр, когда клип не покрывает его целиком (US-527).
+     *
+     * БЕЗ `.default()` НАМЕРЕННО. Дефолт здесь означал бы, что мы выбираем за
+     * клиента, как выглядит его ролик там, где формат не совпал с источником, —
+     * и выбираем МОЛЧА. Отсутствие поля значит «укладки не требуется»; если она
+     * всё же понадобилась, ран обязан сказать об этом в `warnings[]`, а не
+     * подобрать фон по своему вкусу.
+     *
+     * `contain` — вписать целиком (поля видны), `white` — белые поля как у
+     * вендора, `blur` — размытая заливка тем же кадром.
+     */
+    background: z.enum(["white", "blur", "contain"]).optional(),
+};
+/**
+ * Ретрай-параметр агентного скилла: НОМЕР попытки. Живёт в core (не рукописно в
+ * MCP и CLI сразу), но ОТДЕЛЬНО от `makeUgcInputShape` — это вход СКИЛЛА
+ * (порождает суффикс `:N` у ключа идемпотентности в SDK), а не параметр рендера.
+ */
+export const agentRetryShape = { attempt: z.number().int().min(1).optional() };
+/**
+ * Вход make_ugc. Не более одного из person | image задаёт идентичность (оба
+ * опущены → дефолтный актёр). Схема — единый источник правды для REST, MCP
+ * (tools/list) и SDK.
+ *
+ * `character` из взаимоисключения ВЫВЕДЕН, а не забыт: его диспозиция —
+ * `rejected` (`contract-dispositions.ts`), то есть поле отбивается на входе
+ * раньше, чем дойдёт до этой проверки. Держать его здесь значило бы
+ * валидировать выбор между вариантами, один из которых не существует.
+ */
+export const makeUgcInput = z
+    .object(makeUgcInputShape)
+    // Ровно одно из script | segments. Ни одного — рендерить нечего; оба —
+    // непонятно, что говорить, и молча выбрать одно значило бы вернуть ту самую
+    // молчаливую подмену.
+    .refine((v) => (v.script === undefined) !== (v.segments === undefined), {
+    message: "pass exactly one of script | segments",
+})
+    .refine((v) => [v.person, v.image].filter(Boolean).length <= 1, { message: "pass at most one of person | image" })
+    // ПРАВИЛА СЕГМЕНТОВ (US-526). Каждое — ОТДЕЛЬНЫЙ .refine, а не одна проверка
+    // с общим текстом: сообщение обязано называть нарушенное правило, иначе агент
+    // получает «invalid input» и чинит вход перебором. Порядок правил — от того,
+    // что делает ролик невозможным, к тому, что делает его противоречивым.
+    //
+    // Правила живут ЗДЕСЬ, а не в `ugcSegment`: они про массив целиком (сколько
+    // актёров) либо про связь двух полей внутри элемента, а `z.object` элемента
+    // видит только сам элемент.
+    .refine((v) => v.segments === undefined || v.segments.some((s) => s.kind === "actor"), {
+    message: "segments must contain at least one actor segment: nobody speaks otherwise",
+})
+    .refine((v) => v.segments === undefined ||
+    v.segments.filter((s) => s.kind === "actor").length <= MAX_ACTOR_SEGMENTS, {
+    // Потолок ограничивает ОДИН ран, а не суточные траты: денежная граница —
+    // суточный потолок US-537, и путать их значило бы обещать защиту,
+    // которую это число не даёт (PM3, принцип 5 плана).
+    message: `at most ${MAX_ACTOR_SEGMENTS} actor segments per clip`,
+})
+    .refine((v) => v.segments === undefined ||
+    v.segments.every((s) => s.kind !== "actor" || s.script !== undefined), { message: "actor segment requires `script`: it is the line to be spoken" })
+    .refine((v) => v.segments === undefined ||
+    v.segments.every((s) => s.kind !== "actor" || s.media_url === undefined), { message: "actor segment must not carry `media_url`: use a media segment for footage" })
+    .refine((v) => v.segments === undefined ||
+    v.segments.every((s) => s.kind !== "media" || s.media_url !== undefined), { message: "media segment requires `media_url`: there is no footage to show otherwise" })
+    // Голос задаётся ровно одним способом: именем пресета (voice) ИЛИ сырым
+    // вендорским id (voice_id), не обоими сразу. Взаимоисключение — здесь, в
+    // makeUgcInput, а НЕ в makeUgcInputShape: .refine превращает схему в
+    // ZodEffects, у которого нет .shape (ловушка A12), а shape порождает
+    // tools/list. Оба опущены → резолвер подставит дефолт (клон владельца).
+    .refine((v) => !(v.voice !== undefined && v.voice_id !== undefined), { message: "pass at most one of voice | voice_id" })
+    // Скрипт из одних пробелов/пустоты проходит символьный .min(1) выше (там
+    // считаются сырые символы), но даёт 0 произносимых слов — countWords тримит
+    // и схлопывает пробелы. Используем ТУ ЖЕ нормализацию, что и весь пейсинг-гейт
+    // (pacing.ts), не переизобретаем "trim && length".
+    .refine((v) => v.segments !== undefined || countWords(v.script ?? "") >= 1, {
+    message: "script has 0 speakable words",
+})
+    // Счёт СЛОВ, не символов: символьный .max(10_000) выше — грубая защита от
+    // мусорного ввода, а реальный потолок привязан к произносимой длине
+    // (пейсинг-гейт меряет слова/сек, не байты).
+    // Потолок слов считается по ТОМУ из двух, что задан: у сегментного ролика
+    // произносимый текст — это сумма реплик, и мерить его по отсутствующему
+    // `script` значило бы не мерить вовсе.
+    .refine((v) => countWords(spokenTextOf(v)) <= MAX_SCRIPT_WORDS, {
+    error: (issue) => {
+        const wordCount = countWords(spokenTextOf(issue.input));
+        return `script is ~${wordCount} words; ceiling is ${MAX_SCRIPT_WORDS} words (≈${MAX_SCRIPT_SECONDS}s of speech at the pacing gate)`;
+    },
+});
+/** Склейка произносимого текста без проверок — общая база для гейтов и хелпера. */
+function spokenTextOf(input) {
+    if (input.script !== undefined)
+        return input.script;
+    return (input.segments ?? [])
+        .filter((segment) => segment.kind === "actor")
+        .map((segment) => segment.script ?? "")
+        .join(" ");
+}
+/**
+ * ЕДИНСТВЕННОЕ место, где «`script` либо сам, либо склейка сегментов»
+ * превращается в `string`.
+ *
+ * ЗАЧЕМ ХЕЛПЕР, А НЕ `!` НА СЕМИ CALL-SITE'АХ. Снятие обязательности со
+ * `script` делает его `string | undefined` у каждого потребителя, и `.refine`
+ * спасает в рантайме, а компилятор — нет. Самый чувствительный из них —
+ * `elevenlabs-tts.ts`, где комментарий прямо опирался на `z.string().min(1)`
+ * как на ГАРД ПЕРЕД ПЛАТНЫМ POST: заткни мы там типы, гард остался бы снятым,
+ * а компилятор бы об этом молчал. Поэтому проверка непустоты живёт ВНУТРИ
+ * хелпера и восстанавливает гард явно, а не полагается на снятую схему.
+ */
+export function resolvedScript(input) {
+    const text = spokenTextOf(input);
+    if (countWords(text) < 1) {
+        throw new Error("no speakable script: pass script or segments with actor lines");
+    }
+    return text;
+}
+// Тип ВХОДА (`MakeUgcInputArgs`) живёт в `contract-dispositions.ts`: он выводится
+// из ПРЕДЛАГАЕМОГО shape, а не из полного, иначе автокомплит SDK показывал бы
+// отклонённые поля, которые сервер отбивает четырёхсотым (блокер B4).
+export const quoteResponse = z.object({
+    skill: z.string(),
+    credits_estimate: z.number().int().nonnegative(),
+    duration_estimate_sec: z.number().positive(),
+    // несоблюдаемые параметры объявляются заранее, а не молча игнорируются
+    warnings: z.array(z.string()).default([]),
+    // Версия контракта в самом ответе, а не только в заголовке: агент, читающий
+    // quote, обязан видеть, ПОД КАКОЙ контракт он получил цену.
+    contract_version: z.string(),
+    /**
+     * Что мы знаем об источнике кадра. `null` ТОЛЬКО когда `image` дан, но
+     * пробу сделать не удалось — отсутствие `image` источником не является, там
+     * стоит дефолтный актёр со своими размерами. Это и есть превращение
+     * невидимой константы в наблюдаемую величину: агент видит, ПОЧЕМУ формат
+     * получился таким, ещё до платного рендера.
+     */
+    source: z
+        .object({
+        width: z.number().positive(),
+        height: z.number().positive(),
+        aspect_ratio: z.string(),
+    })
+        .nullable(),
+    /** Формат, который реально будет отрендерен на этом входе. */
+    resolved_aspect_ratio: z.enum(ASPECT_RATIOS),
+});
+//# sourceMappingURL=skills.js.map

package/dist/skills.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.js","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"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"}

package/dist/tts-backend.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Вендор-нейтральный контракт синтеза речи.
+ *
+ * ЗАЧЕМ отдельно от рендера: провайдеры TTS меняются независимо от провайдеров
+ * аватара, и «ElevenLabs + HeyGen» — лишь одна из комбинаций.
+ *
+ * Ключевая причина существования этого файла — ТАЙМИНГИ. ElevenLabs отдаёт их
+ * ПОСИМВОЛЬНО (проверено 18.07.2026: 134 символа → 134 тайминга), а этап B
+ * ждёт пословные для `createTikTokStyleCaptions()`. Другой провайдер отдаст
+ * пословные сразу или не отдаст вовсе. Нормализация обязана происходить в
+ * адаптере, иначе посимвольный формат ElevenLabs протечёт в пайплайн субтитров
+ * и намертво привяжет нас к вендору.
+ */
+/** Тайминг одного слова. Единица, в которой пайплайн субтитров думает. */
+export interface WordTiming {
+    word: string;
+    startSec: number;
+    endSec: number;
+}
+export interface SpeechRequest {
+    text: string;
+    /** Идентификатор голоса в терминах бэкенда. Маппинг наших пресетов — забота адаптера. */
+    voiceId: string;
+    /** Наш run_id — для идемпотентности и трассировки на стороне вендора. */
+    runId: string;
+}
+export interface SpeechResult {
+    audio: Uint8Array;
+    mimeType: string;
+    durationSec: number;
+    /**
+     * Пословные тайминги. `null` — бэкенд их не отдаёт вовсе; тогда пайплайн
+     * субтитров обязан добывать их отдельно (Whisper), и это должно быть видно
+     * по типу, а не выясняться в рантайме.
+     *
+     * Адаптер обязан отдавать ПОСЛОВНЫЕ тайминги, даже если вендор отдал
+     * посимвольные: агрегация — его работа, а не работа потребителя.
+     */
+    words: WordTiming[] | null;
+}
+export interface TtsCapabilities {
+    /** Максимум символов за запрос. null — вендор не документирует (случай ElevenLabs). */
+    maxChars: number | null;
+    /** Отдаёт ли тайминги вообще. */
+    providesTimings: boolean;
+    /**
+     * Сколько запросов можно вести параллельно. У ElevenLabs зависит от тарифа
+     * (Creator = 5) и упрётся раньше лимитов рендера при мульти-тейке в этапе B.
+     */
+    maxConcurrency: number | null;
+}
+export interface TtsBackend {
+    readonly name: string;
+    readonly capabilities: TtsCapabilities;
+    synthesize(req: SpeechRequest): Promise<SpeechResult>;
+}
+/**
+ * Склейка посимвольных таймингов в пословные.
+ *
+ * Живёт здесь, а не в адаптере ElevenLabs, потому что посимвольный формат
+ * встречается у нескольких вендоров, и переписывать эту логику под каждого —
+ * лишняя работа с одинаковыми граничными случаями.
+ *
+ * Границей слова считается пробельный символ; сам пробел в слово не входит,
+ * но и не рвёт уже начатое. Пустые слова не порождаются.
+ */
+export declare function charTimingsToWords(characters: readonly string[], startTimes: readonly number[], endTimes: readonly number[]): WordTiming[];