@clipwright/core 0.19.0 → 0.20.0

package/dist/voice-listing.js

@@ -2,12 +2,12 @@ import { z } from "zod";
 import { CATALOG_LANGUAGES, normalizeVoiceLabel, VOICES_QUERY_FIELDS, voicesQueryShape, } from "./voice-catalog.js";
 import { TTS_MODEL_LANGUAGES, VOICE_CATALOG } from "./voice-catalog-data.js";
 import { resolveTtsModel, TTS_MODEL_CHAR_CAP, TTS_MODELS, VOICE_PRESETS, } from "./voices.js";
-// Подпуть, а не баррел: список читает каталог, а клиентам SDK он не нужен (docs/16).
-// Те же данные сверяет с вендором еженедельная проба воркера.
+// A subpath, not the barrel: the list reads the catalog, which SDK clients do not need.
+// A weekly worker probe checks the same data against the vendor.
 export { TTS_MODEL_LANGUAGES, VOICE_CATALOG } from "./voice-catalog-data.js";
 const isLive = (voice) => voice.retired_at === undefined;
-/** Модели, под которые вендор ВООБЩЕ выдаёт верификацию голосам библиотеки. */
-/** Выводится из каталога, а не перечисляется: разбор — `docs/16` (#208). */
+/** Models for which the vendor verifies ANY library voice at all. Derived from the */
+/** catalog, not listed. */
 export function vendorVerifiedModels(voices = VOICE_CATALOG.voices) {
     return TTS_MODELS.filter((model) => voices.some((voice) => isLive(voice) && voice.verified_models.includes(model)));
 }
@@ -15,7 +15,7 @@ function labelValues(voices, raw) {
     const values = voices.filter(isLive).map((voice) => normalizeVoiceLabel(raw(voice)));
     return [...new Set(values.filter((value) => value !== undefined))].sort();
 }
-/** Запрос `/v1/voices` на сервере: незнакомая метка — отказ со списком допустимых, а не пустой список. */
+/** The server's `/v1/voices` query: an unfamiliar label is refused with the allowed list, not an empty result. */
 export function serverVoicesQueryFor(voices = VOICE_CATALOG.voices) {
     return z.object({
         ...voicesQueryShape,
@@ -25,7 +25,7 @@ export function serverVoicesQueryFor(voices = VOICE_CATALOG.voices) {
 }
 export const serverVoicesQuery = serverVoicesQueryFor();
 const presentText = (raw) => raw?.trim() || undefined;
-/** Пресеты, затем живые голоса каталога по языку и рангу; поле, которого у голоса нет, не совпадает ни с чем. */
+/** Presets, then live catalog voices by language and rank; a field the voice lacks matches nothing. */
 export function listVoices(query, catalog = VOICE_CATALOG, modelLanguages = TTS_MODEL_LANGUAGES) {
     const languagesOf = (id) => modelLanguages.models.find((model) => model.id === id)?.languages ?? [];
     const supportedModels = (language) => TTS_MODELS.filter((id) => languagesOf(id).includes(language));

package/dist/voice-listing.js.map

@@ -1 +1 @@
-{"version":3,"file":"voice-listing.js","sourceRoot":"","sources":["../src/voice-listing.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"voice-listing.js","sourceRoot":"","sources":["../src/voice-listing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,GAKjB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7E,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,UAAU,EACV,aAAa,GAEd,MAAM,aAAa,CAAC;AAErB,wFAAwF;AACxF,iEAAiE;AACjE,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE7E,MAAM,MAAM,GAAG,CAAC,KAAuB,EAAW,EAAE,CAAC,KAAK,CAAC,UAAU,KAAK,SAAS,CAAC;AAEpF,sFAAsF;AACtF,2BAA2B;AAC3B,MAAM,UAAU,oBAAoB,CAClC,MAAM,GAAgC,aAAa,CAAC,MAAM;IAE1D,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CACjC,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,eAAe,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAC/E,CAAC;AACJ,CAAC;AAED,SAAS,WAAW,CAAC,MAAmC,EAAE,GAA+C;IACvG,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,mBAAmB,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACrF,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,EAA2B,CAAC;AACrG,CAAC;AAED,kHAAkH;AAClH,MAAM,UAAU,oBAAoB,CAAC,MAAM,GAAgC,aAAa,CAAC,MAAM;IAC7F,OAAO,CAAC,CAAC,MAAM,CAAC;QACd,GAAG,gBAAgB;QACnB,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,EAAE;QACrE,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,QAAQ,EAAE;KAChF,CAAC,CAAC;AACL,CAAC;AACD,MAAM,CAAC,MAAM,iBAAiB,GAAG,oBAAoB,EAAE,CAAC;AAExD,MAAM,WAAW,GAAG,CAAC,GAAkB,EAAsB,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,SAAS,CAAC;AAEzF,uGAAuG;AACvG,MAAM,UAAU,UAAU,CACxB,KAAkB,EAClB,OAAO,GAAqB,aAAa,EACzC,cAAc,GAA0B,mBAAmB;IAK3D,MAAM,WAAW,GAAG,CAAC,EAAU,EAAY,EAAE,CAAC,cAAc,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,SAAS,IAAI,EAAE,CAAC;IACtH,MAAM,eAAe,GAAG,CAAC,QAAgB,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;IAE5G,MAAM,OAAO,GAAwB,MAAM,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC;QAC1F,IAAI;QACJ,IAAI,EAAE,QAAQ;QACd,GAAG,MAAM;QACT,gBAAgB,EAAE,eAAe,CAAC,MAAM,CAAC,QAAQ,CAAC;KACnD,CAAC,CAAC,CAAC;IACJ,MAAM,YAAY,GAAG,CAAC,KAAuB,EAAE,EAAE,CAAC,iBAAiB,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC5F,MAAM,aAAa,GAAwB,OAAO,CAAC,MAAM;SACtD,MAAM,CAAC,MAAM,CAAC;SACd,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;SAClG,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QACf,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,IAAI,EAAE,SAAS;QACf,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,MAAM,EAAE,WAAW,CAAC,KAAK,CAAC,MAAM,CAAC;QACjC,MAAM,EAAE,WAAW,CAAC,KAAK,CAAC,MAAM,CAAC;QACjC,MAAM,EAAE,mBAAmB,CAAC,KAAK,CAAC,UAAU,CAAC;QAC7C,GAAG,EAAE,mBAAmB,CAAC,KAAK,CAAC,OAAO,CAAC;QACvC,QAAQ,EAAE,mBAAmB,CAAC,KAAK,CAAC,YAAY,CAAC;QACjD,WAAW,EAAE,WAAW,CAAC,KAAK,CAAC,WAAW,CAAC,IAAI,KAAK,CAAC,IAAI;QACzD,KAAK,EAAE,eAAe,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC;QAC7C,gBAAgB,EAAE,eAAe,CAAC,KAAK,CAAC,QAAQ,CAAC;QACjD,eAAe,EAAE,KAAK,CAAC,eAAe;KACvC,CAAC,CAAC,CAAC;IAEN,MAAM,OAAO,GAAG,CAAC,KAAwB,EAAW,EAAE,CACpD,mBAAmB,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;QAClC,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;QAC5B,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;QACtC,IAAI,KAAK,KAAK,OAAO;YAAE,OAAO,KAAK,CAAC,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC;QAChF,OAAO,KAAK,CAAC,KAAK,CAAC,KAAK,MAAM,CAAC;IACjC,CAAC,CAAC,CAAC;IAEL,OAAO;QACL,MAAM,EAAE,CAAC,GAAG,OAAO,EAAE,GAAG,aAAa,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC;QACtD,MAAM,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;YAC9B,EAAE;YACF,UAAU,EAAE,kBAAkB,CAAC,EAAE,CAAC;YAClC,SAAS,EAAE,WAAW,CAAC,EAAE,CAAC;YAC1B,sBAAsB,EAAE,oBAAoB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC;SAC1E,CAAC,CAAC;KACJ,CAAC;AACJ,CAAC"}

package/dist/voices.d.ts

@@ -1,41 +1,40 @@
 import { z } from "zod";
 import type { Gender } from "./default-actor.js";
-/** Модели синтеза ElevenLabs, которые контракт разрешает назвать (clipwright#101, #145). */
-/** `multilingual_v2` снята: по замеру #145 она не отвечает ни на один приём ударения. */
+/** ElevenLabs speech models the contract lets callers name. `multilingual_v2` was dropped: */
+/** it honored none of the stress-marking methods we measured. */
 export declare const TTS_MODELS: readonly ["eleven_v3", "eleven_flash_v2_5", "eleven_turbo_v2_5"];
 export type TtsModelId = (typeof TTS_MODELS)[number];
 export declare const DEFAULT_TTS_MODEL: TtsModelId;
-/** У v3 потолок вендорский. У 2.5 вендор даёт 40 000; 10 000 — наш потолок длины рана. */
+/** The v3 cap is the vendor's. For 2.5 the vendor allows 40,000; 10,000 is our run-length cap. */
 export declare const TTS_MODEL_CHAR_CAP: Readonly<Record<TtsModelId, number>>;
-/** Знак ударения U+0301 читает только v3; flash тем же знаком ошибается втрое чаще (#145). */
+/** Only v3 reads the U+0301 stress mark; flash misreads the same mark three times as often. */
 export declare const STRESS_MARK: string;
 export declare const STRESS_MARK_MODELS: ReadonlySet<TtsModelId>;
-/** «потОм» → «пото́м». Заглавная в начале слова — обычная заглавная; знак не удваивается. */
+/** Turns an inner capital vowel into a stress mark. A word-initial capital stays a capital; */
+/** an existing mark is not doubled. */
 export declare function stressMarksFromCapitals(text: string): string;
-/** Текст, который уходит вендору: разметка ударения — только для модели, которая её читает. */
+/** The text sent to the vendor: stress marking only for a model that reads it. */
 export declare function speechTextFor(text: string, modelId: TtsModelId): string;
 export declare const MAX_SCRIPT_CHARS: number;
 export declare const SCRIPT_LENGTH_DESCRIPTION: string;
 export declare const STRESS_MARKING_DESCRIPTION: string;
-/** Длина считается по тексту, который уйдёт вендору, — со знаками ударения. */
+/** Length is measured on the text sent to the vendor, stress marks included. */
 export declare function ttsScriptLimitError(text: string, modelId: string): string | undefined;
-/** Каталог голосовых пресетов — НАШИ имена и метадата, БЕЗ вендорских id: имена */
-/** порождают `tools/list` и типы SDK, id живут только в адаптере воркера. */
+/** Voice preset catalog: OUR names and metadata, WITHOUT vendor ids. Names feed `tools/list` */
+/** and SDK types; ids live only in the worker adapter. */
 export interface VoicePreset {
-    /** Язык голоса в терминах BCP-47-подобного короткого кода (ru/en). */
+    /** Voice language as a short BCP-47-like code (ru/en). */
     language: string;
-    /** Пол голоса. Опускается, только если он НАМ неизвестен: молчание вендора */
-    /** про наш собственный клон незнанием не является (docs/18, Д50). */
+    /** Voice gender. Omitted only when WE do not know it: vendor silence about our own */
+    /** clone is not ignorance. */
     gender?: Gender;
-    /** Человекочитаемое описание для list_voices (US-516). */
+    /** Human-readable description for list_voices. */
     description: string;
-    /** Модель синтеза, на которую голос настроен; клиент может перебить полем `tts_model`. */
+    /** The speech model the voice is tuned for; clients may override with `tts_model`. */
     model: TtsModelId;
 }
-/**
- * Стартовый набор из 5 пресетов (условие плана §4). Порядок значим только для
- * презентации; дефолт задаётся отдельно через `DEFAULT_VOICE_PRESET`.
- */
+/** The starter set of presets. Order matters only for presentation; the default is set */
+/** separately by `DEFAULT_VOICE_PRESET`. */
 export declare const VOICE_PRESETS: {
     readonly owner_ru_clone: {
         readonly language: "ru";
@@ -68,17 +67,15 @@ export declare const VOICE_PRESETS: {
         readonly model: "eleven_v3";
     };
 };
-/**
- * Кортеж имён пресетов для `z.enum`. Выводится из ключей `VOICE_PRESETS`, чтобы
- * список имён и метадата не разъехались (правило проекта №2 — не дублировать).
- */
+/** Preset name tuple for `z.enum`, derived from `VOICE_PRESETS` keys so names and */
+/** metadata cannot drift. */
 export declare const VOICE_PRESET_NAMES: [keyof typeof VOICE_PRESETS, ...(keyof typeof VOICE_PRESETS)[]];
 export type VoicePresetName = keyof typeof VOICE_PRESETS;
-/** Форма имени голоса, а не список: каталог растёт на сервере без выпуска клиентов (#164). */
+/** The shape of a voice name, not a list: the catalog grows on the server without client releases. */
 export declare const VOICE_NAME_PATTERN: RegExp;
 export declare function isVoicePresetName(name: string): name is VoicePresetName;
-/** Ответ `/v1/voices` — схема, а не догадка обеих сторон. Сервер отдаёт разобранное */
-/** ею тело, SDK разбирает им же: `Array.isArray` пропускал массив чего угодно. */
+/** The `/v1/voices` response as a schema, not a guess on both sides: the server sends a */
+/** body parsed by it and the SDK parses with it. `Array.isArray` let any array through. */
 export declare const voiceCatalogEntry: z.ZodObject<{
     name: z.ZodString;
     kind: z.ZodOptional<z.ZodString>;
@@ -135,28 +132,18 @@ export declare const voicesResponse: z.ZodObject<{
     }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type VoicesResponse = z.infer<typeof voicesResponse>;
-/** Голос, когда пол актёра неизвестен; подставляет резолвер, а не схема (US-517). */
-/** История выбора дефолта — docs/16. */
+/** The voice when the actor's gender is unknown; the resolver fills it in, not the schema. */
 export declare const DEFAULT_VOICE_PRESET: "george";
-/** Голос по умолчанию следует полу актёра (clipwright#183, docs/18, Д52). */
+/** The default voice follows the actor's gender. */
 export declare const DEFAULT_VOICE_BY_GENDER: {
     readonly female: "sarah";
     readonly male: "george";
 };
-/**
- * Форма сырого `voice_id` вендора. НАМЕРЕННО терпимая (16–32 алфанумерик):
- * ElevenLabs не документирует формат id, наблюдаемые id — 20 символов, но
- * строгая длина 20 превратила бы будущий валидный id иной длины в ложный
- * отказ. Это лишь грубый фильтр мусора на входе; реальную проверку
- * существования id делает бесплатный префлайт в воркере (US-515).
- */
+/** Shape of a raw vendor `voice_id`, deliberately loose (16–32 alphanumerics): the format is */
+/** undocumented. A coarse input filter only; the worker's free preflight checks existence. */
 export declare const VOICE_ID_PATTERN: RegExp;
-/**
- * Результат разрешения выбора голоса — дискриминированное объединение. `preset`
- * несёт НАШЕ имя (адаптер превратит его в вендорский id через `PRESET_TO_VOICE_ID`),
- * `raw` — уже сырой вендорский id (escape hatch). Core НЕ знает вендорских id, и
- * это объединение — граница: дальше маппинг делает адаптер (принцип 5).
- */
+/** Resolved voice selection. `preset` carries OUR name, mapped to a vendor id by the adapter; */
+/** `raw` is already a vendor id. Core never knows vendor ids. */
 export type VoiceSelection = {
     kind: "preset";
     preset: VoicePresetName;
@@ -167,68 +154,39 @@ export type VoiceSelection = {
     kind: "raw";
     voiceId: string;
 };
-/** Приоритет: сырой `voice_id` > `voice` > голос по полу актёра > `DEFAULT_VOICE_PRESET`. */
-/** Пол даёт `voiceGenderFor` (actors.ts); взаимоисключение полей держит `makeUgcInput`. */
+/** Priority: raw `voice_id` > `voice` > voice by actor gender > `DEFAULT_VOICE_PRESET`. */
+/** Gender comes from `voiceGenderFor` (actors.ts); `makeUgcInput` enforces exclusivity. */
 export declare function resolveVoiceSelection(input: {
     voice?: string | undefined;
     voice_id?: string | undefined;
 }, gender?: Gender | undefined): VoiceSelection;
-/** Модель: явное `tts_model` → модель пресета → дефолт (сырой `voice_id` пресета не имеет). */
-/** Голос каталога говорит на дефолте, как пресеты (решение владельца #164). */
+/** Model: explicit `tts_model` → the preset's model → default (a raw `voice_id` has no preset). */
+/** A catalog voice speaks the default model, like the presets. */
 export declare function resolveTtsModel(input: {
     voice?: string | undefined;
     voice_id?: string | undefined;
     tts_model?: TtsModelId | undefined;
 }, gender?: Gender | undefined): TtsModelId;
-/**
- * Семейство письменности скрипта — грубый детектор для языкового warning'а
- * (US-517). Считает ТОЛЬКО буквенные символы: кириллица (U+0400–U+04FF) против
- * латиницы (A–Z/a–z). Знаки препинания, цифры, пробелы, эмодзи игнорируются —
- * они не различают язык.
- *
- * НЕЙТРАЛЬНАЯ ПОЛОСА (детерминированно, тестируемо):
- *  - < 2 букв всего (пусто, одни цифры, единичная буква-случайность) → "neutral":
- *    данных для суждения нет (это «мало букв» из плана §Р3, условие ii);
- *  - ни одна сторона не набрала порога доминирования 60% (напр. смесь 50/50) →
- *    "neutral": язык скрипта неоднозначен, warning выдавать не на чем.
- * Только уверенное доминирование (≥60%) даёт "cyrillic"/"latin".
- */
+/** Script family for the language warning: counts only Cyrillic vs Latin letters. Fewer than */
+/** 2 letters or no side reaching this 60% dominance gives "neutral". */
 export declare const SCRIPT_DOMINANCE_THRESHOLD = 0.6;
-/** Буквы каждого письма по отдельности. Их же складывает `detectScriptFamily`; */
-/** отдельно они нужны, чтобы отличить «мало» от «нет вовсе» (clipwright#131). */
+/** Letters of each script separately. `detectScriptFamily` sums them; apart they tell */
+/** "few" from "none at all". */
 export declare function scriptLetterCounts(script: string): {
     cyrillic: number;
     latin: number;
 };
 export declare function detectScriptFamily(script: string): "cyrillic" | "latin" | "neutral";
-/** Только путь QUOTE (US-517); почему не на пути рана — docs/18, Д41. */
+/** QUOTE path only: a raw voice id is checked at run start, not at quote time. */
 export declare const RAW_VOICE_ID_VALIDATION_WARNING = "raw voice_id is verified against your account at run start, not at quote time";
-/**
- * Голосовые warnings по ТЕСТУ ДОПУСТИМОСТИ (план §Р3). Warning допустим, только
- * если ОДНОВРЕМЕННО: (i) причина — то, что клиент запросил ЯВНО (не дефолт, не наш
- * выбор); (ii) утверждение опирается на данные, которые ЕСТЬ (лейбл присутствует),
- * а не на их отсутствие; (iii) на дефолтном happy-path не срабатывает НИКОГДА.
- *
- * ПРАВИЛО СТАРШИНСТВА ПОДМЕНЫ: подмена (клиент попросил X, отдали Y) предупреждает
- * ВСЕГДА, независимо от (iii) — (iii) глушит уведомления о ПРАВИЛЬНОМ поведении, не
- * о деградированном. Канон такой подмены — 1080p→720p (render-backend.ts:144). В
- * ДАННОМ дизайне подмены голоса НЕТ: путь падает closed (сырой id не найден → бросок
- * до платного POST, US-515; неизвестное имя → 400 на границе enum), голос молча не
- * заменяется. Поэтому правило старшинства здесь не применяется — но зафиксировано,
- * чтобы будущая подмена не была ошибочно заглушена условием (iii).
- *
- * ПОЧЕМУ тест не подавляет обязательный warning про подмену №3 (принцип DR-2):
- * обязанность №3 крепится к НЕИСПОЛНЕННОМУ явному запросу (клиент попросил 1080p,
- * дали 720p) — это подмена, у неё старшинство над (iii). Здесь же голос либо
- * исполняется как запрошен, либо ран падает — деградированной выдачи под видом
- * успешной не бывает, глушить нечего.
- */
+/** Voice warnings fire only when (i) the client chose explicitly, (ii) the claim rests on data */
+/** present, (iii) never on the default happy path. A voice is never substituted, only failed. */
 export declare function buildVoiceWarnings(input: {
     voice?: string | undefined;
     voice_id?: string | undefined;
     script: string;
 }): string[];
-/** Модель, не читающая ударения, на тексте, где они важны. На умолчании (v3) молчит всегда. */
+/** A model that ignores stress marks on text where they matter. Silent on the v3 default. */
 export declare function buildSpeechModelWarnings(input: {
     voice?: string | undefined;
     voice_id?: string | undefined;

package/dist/voices.js

@@ -1,15 +1,15 @@
 import { z } from "zod";
-/** Модели синтеза ElevenLabs, которые контракт разрешает назвать (clipwright#101, #145). */
-/** `multilingual_v2` снята: по замеру #145 она не отвечает ни на один приём ударения. */
+/** ElevenLabs speech models the contract lets callers name. `multilingual_v2` was dropped: */
+/** it honored none of the stress-marking methods we measured. */
 export const TTS_MODELS = ["eleven_v3", "eleven_flash_v2_5", "eleven_turbo_v2_5"];
 export const DEFAULT_TTS_MODEL = "eleven_v3";
-/** У v3 потолок вендорский. У 2.5 вендор даёт 40 000; 10 000 — наш потолок длины рана. */
+/** The v3 cap is the vendor's. For 2.5 the vendor allows 40,000; 10,000 is our run-length cap. */
 export const TTS_MODEL_CHAR_CAP = {
     eleven_v3: 5_000,
     eleven_flash_v2_5: 10_000,
     eleven_turbo_v2_5: 10_000,
 };
-/** Знак ударения U+0301 читает только v3; flash тем же знаком ошибается втрое чаще (#145). */
+/** Only v3 reads the U+0301 stress mark; flash misreads the same mark three times as often. */
 export const STRESS_MARK = String.fromCharCode(0x0301);
 export const STRESS_MARK_MODELS = new Set(["eleven_v3"]);
 const CYRILLIC_WORD = new RegExp(`[Ѐ-ӿ${STRESS_MARK}]+`, "g");
@@ -17,8 +17,8 @@ const CYRILLIC_STRESS_MARK = new RegExp(`[Ѐ-ӿ]${STRESS_MARK}`);
 const CYRILLIC_LOWERCASE = /[а-џ]/;
 const CYRILLIC_UPPERCASE = /[Ѐ-Я]/;
 const CYRILLIC_UPPER_VOWELS = "АЕЁИОУЫЭЮЯ";
-/** Позиция ударной заглавной: ровно одна заглавная после первой буквы, и она гласная. */
-/** Вторая заглавная или согласная — аббревиатура («ВУЗы», «СУПЕРцена»), не ударение. */
+/** Index of the stressed capital: exactly one capital after the first letter, a vowel. */
+/** A second capital or a consonant capital is an abbreviation, not stress. */
 function stressCapitalIndex(word) {
     if (!CYRILLIC_LOWERCASE.test(word))
         return -1;
@@ -36,7 +36,8 @@ function stressCapitalIndex(word) {
     }
     return found;
 }
-/** «потОм» → «пото́м». Заглавная в начале слова — обычная заглавная; знак не удваивается. */
+/** Turns an inner capital vowel into a stress mark. A word-initial capital stays a capital; */
+/** an existing mark is not doubled. */
 export function stressMarksFromCapitals(text) {
     return text.replace(CYRILLIC_WORD, (word) => {
         const i = stressCapitalIndex(word);
@@ -47,7 +48,7 @@ export function stressMarksFromCapitals(text) {
         return word.slice(0, i) + vowel.toLowerCase() + mark + word.slice(i + 1);
     });
 }
-/** Текст, который уходит вендору: разметка ударения — только для модели, которая её читает. */
+/** The text sent to the vendor: stress marking only for a model that reads it. */
 export function speechTextFor(text, modelId) {
     return STRESS_MARK_MODELS.has(modelId) ? stressMarksFromCapitals(text) : text;
 }
@@ -62,7 +63,7 @@ export const STRESS_MARKING_DESCRIPTION = "Russian stress: write the stressed vo
     "read as stress, so write \"Яндекс Еда\", not \"ЯндексЕда\". " +
     "Tell users writing in Russian that they can mark stress this way. eleven_flash_v2_5 and " +
     "eleven_turbo_v2_5 cost less but misread stress marks: capitals reach them unchanged.";
-/** Длина считается по тексту, который уйдёт вендору, — со знаками ударения. */
+/** Length is measured on the text sent to the vendor, stress marks included. */
 export function ttsScriptLimitError(text, modelId) {
     const model = TTS_MODELS.find((model) => model === modelId);
     if (!model)
@@ -78,19 +79,17 @@ export function ttsScriptLimitError(text, modelId) {
     }
     return undefined;
 }
-/**
- * Стартовый набор из 5 пресетов (условие плана §4). Порядок значим только для
- * презентации; дефолт задаётся отдельно через `DEFAULT_VOICE_PRESET`.
- */
+/** The starter set of presets. Order matters only for presentation; the default is set */
+/** separately by `DEFAULT_VOICE_PRESET`. */
 export const VOICE_PRESETS = {
     owner_ru_clone: {
         language: "ru",
-        // Пол — НАШ факт о своём клоне, а не метадата вендора (docs/18, Д50).
+        // The gender is OUR fact about our own clone, not vendor metadata.
         gender: "male",
         description: "Клон голоса владельца (David-Dmitry-Ru); русский — на английском даёт акцент",
         model: "eleven_v3",
     },
-    // Все пресеты — v3: решение владельца #145, выразительнее и единственная со знаком ударения.
+    // Every preset is v3: more expressive, and the only model that reads stress marks.
     sarah: {
         language: "en",
         gender: "female",
@@ -116,20 +115,18 @@ export const VOICE_PRESETS = {
         model: "eleven_v3",
     },
 };
-/**
- * Кортеж имён пресетов для `z.enum`. Выводится из ключей `VOICE_PRESETS`, чтобы
- * список имён и метадата не разъехались (правило проекта №2 — не дублировать).
- */
+/** Preset name tuple for `z.enum`, derived from `VOICE_PRESETS` keys so names and */
+/** metadata cannot drift. */
 export const VOICE_PRESET_NAMES = Object.keys(VOICE_PRESETS);
-/** Форма имени голоса, а не список: каталог растёт на сервере без выпуска клиентов (#164). */
+/** The shape of a voice name, not a list: the catalog grows on the server without client releases. */
 export const VOICE_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
 export function isVoicePresetName(name) {
     return Object.hasOwn(VOICE_PRESETS, name);
 }
-/** Ответ `/v1/voices` — схема, а не догадка обеих сторон. Сервер отдаёт разобранное */
-/** ею тело, SDK разбирает им же: `Array.isArray` пропускал массив чего угодно. */
+/** The `/v1/voices` response as a schema, not a guess on both sides: the server sends a */
+/** body parsed by it and the SDK parses with it. `Array.isArray` let any array through. */
 export const voiceCatalogEntry = z.object({
-    // Строки, а не enum: незнакомое клиенту имя или метка не роняют `listVoices` (#164).
+    // Strings, not enums: an unfamiliar name or label does not break `listVoices`.
     name: z.string().min(1),
     kind: z.string().optional(),
     language: z.string().min(1).optional(),
@@ -142,7 +139,7 @@ export const voiceCatalogEntry = z.object({
     model: z.enum(TTS_MODELS),
     supported_models: z.array(z.string()).optional(),
     verified_models: z.array(z.string()).optional(),
-    // Подпись временная; отсутствие пары значит «образца у голоса нет» (docs/16).
+    // The signature is temporary; a missing pair means the voice has no sample.
     preview_url: z.url().optional(),
     preview_expires_at: z.iso.datetime().optional(),
 });
@@ -150,18 +147,17 @@ export const voiceModelEntry = z.object({
     id: z.string().min(1),
     char_limit: z.number().int().positive(),
     languages: z.array(z.string()),
-    /** Выдаёт ли вендор верификацию под эту модель хоть одному голосу библиотеки. */
-    /** Пустой `verified_models` у модели, где `false`, о голосе не говорит (#208). */
+    /** Whether the vendor verifies any library voice for this model at all. An empty */
+    /** `verified_models` on a model where this is `false` says nothing about the voice. */
     vendor_verifies_voices: z.boolean().optional(),
 });
 export const voicesResponse = z.object({
     voices: z.array(voiceCatalogEntry),
     models: z.array(voiceModelEntry).optional(),
 });
-/** Голос, когда пол актёра неизвестен; подставляет резолвер, а не схема (US-517). */
-/** История выбора дефолта — docs/16. */
+/** The voice when the actor's gender is unknown; the resolver fills it in, not the schema. */
 export const DEFAULT_VOICE_PRESET = "george";
-/** Голос по умолчанию следует полу актёра (clipwright#183, docs/18, Д52). */
+/** The default voice follows the actor's gender. */
 export const DEFAULT_VOICE_BY_GENDER = {
     female: "sarah",
     male: "george",
@@ -169,30 +165,25 @@ export const DEFAULT_VOICE_BY_GENDER = {
 function defaultVoiceFor(gender) {
     return gender === undefined ? DEFAULT_VOICE_PRESET : DEFAULT_VOICE_BY_GENDER[gender];
 }
-/**
- * Форма сырого `voice_id` вендора. НАМЕРЕННО терпимая (16–32 алфанумерик):
- * ElevenLabs не документирует формат id, наблюдаемые id — 20 символов, но
- * строгая длина 20 превратила бы будущий валидный id иной длины в ложный
- * отказ. Это лишь грубый фильтр мусора на входе; реальную проверку
- * существования id делает бесплатный префлайт в воркере (US-515).
- */
+/** Shape of a raw vendor `voice_id`, deliberately loose (16–32 alphanumerics): the format is */
+/** undocumented. A coarse input filter only; the worker's free preflight checks existence. */
 export const VOICE_ID_PATTERN = /^[A-Za-z0-9]{16,32}$/;
-/** Приоритет: сырой `voice_id` > `voice` > голос по полу актёра > `DEFAULT_VOICE_PRESET`. */
-/** Пол даёт `voiceGenderFor` (actors.ts); взаимоисключение полей держит `makeUgcInput`. */
+/** Priority: raw `voice_id` > `voice` > voice by actor gender > `DEFAULT_VOICE_PRESET`. */
+/** Gender comes from `voiceGenderFor` (actors.ts); `makeUgcInput` enforces exclusivity. */
 export function resolveVoiceSelection(input, gender) {
     if (input.voice_id !== undefined) {
         return { kind: "raw", voiceId: input.voice_id };
     }
     if (input.voice !== undefined) {
-        // Не пресет — слаг каталога: его id знает только сайдкар воркера, промах там — отказ (#164).
+        // Not a preset, so a catalog slug: only the worker sidecar knows its id; a miss there refuses.
         if (!isVoicePresetName(input.voice))
             return { kind: "catalog", slug: input.voice };
         return { kind: "preset", preset: input.voice };
     }
     return { kind: "preset", preset: defaultVoiceFor(gender) };
 }
-/** Модель: явное `tts_model` → модель пресета → дефолт (сырой `voice_id` пресета не имеет). */
-/** Голос каталога говорит на дефолте, как пресеты (решение владельца #164). */
+/** Model: explicit `tts_model` → the preset's model → default (a raw `voice_id` has no preset). */
+/** A catalog voice speaks the default model, like the presets. */
 export function resolveTtsModel(input, gender) {
     if (input.tts_model !== undefined)
         return input.tts_model;
@@ -201,22 +192,11 @@ export function resolveTtsModel(input, gender) {
     const voice = input.voice ?? defaultVoiceFor(gender);
     return isVoicePresetName(voice) ? VOICE_PRESETS[voice].model : DEFAULT_TTS_MODEL;
 }
-/**
- * Семейство письменности скрипта — грубый детектор для языкового warning'а
- * (US-517). Считает ТОЛЬКО буквенные символы: кириллица (U+0400–U+04FF) против
- * латиницы (A–Z/a–z). Знаки препинания, цифры, пробелы, эмодзи игнорируются —
- * они не различают язык.
- *
- * НЕЙТРАЛЬНАЯ ПОЛОСА (детерминированно, тестируемо):
- *  - < 2 букв всего (пусто, одни цифры, единичная буква-случайность) → "neutral":
- *    данных для суждения нет (это «мало букв» из плана §Р3, условие ii);
- *  - ни одна сторона не набрала порога доминирования 60% (напр. смесь 50/50) →
- *    "neutral": язык скрипта неоднозначен, warning выдавать не на чем.
- * Только уверенное доминирование (≥60%) даёт "cyrillic"/"latin".
- */
+/** Script family for the language warning: counts only Cyrillic vs Latin letters. Fewer than */
+/** 2 letters or no side reaching this 60% dominance gives "neutral". */
 export const SCRIPT_DOMINANCE_THRESHOLD = 0.6;
-/** Буквы каждого письма по отдельности. Их же складывает `detectScriptFamily`; */
-/** отдельно они нужны, чтобы отличить «мало» от «нет вовсе» (clipwright#131). */
+/** Letters of each script separately. `detectScriptFamily` sums them; apart they tell */
+/** "few" from "none at all". */
 export function scriptLetterCounts(script) {
     let cyrillic = 0;
     let latin = 0;
@@ -233,7 +213,7 @@ export function scriptLetterCounts(script) {
 export function detectScriptFamily(script) {
     const { cyrillic, latin } = scriptLetterCounts(script);
     const total = cyrillic + latin;
-    // «Мало букв» → нейтрально: судить о языке не на чем (условие ii — данных нет).
+    // Too few letters: nothing to judge the language by.
     if (total < 2) {
         return "neutral";
     }
@@ -245,70 +225,47 @@ export function detectScriptFamily(script) {
     }
     return "neutral";
 }
-/**
- * Отображение нашего короткого языкового лейбла пресета в семейство письменности.
- * НАМЕРЕННО охватывает только языки, которые мы реально размечаем (ru/en): лейбл
- * вне этого набора трактуется как «нет данных для сравнения» и глушит warning
- * (условие ii — утверждение опирается на присутствующие данные, а не на догадку).
- */
+/** Maps our short preset language label to a script family. Covers only ru/en on purpose: */
+/** any other label means "no data to compare" and silences the warning. */
 const LANGUAGE_TO_SCRIPT_FAMILY = {
     ru: "cyrillic",
     en: "latin",
 };
-/** Только путь QUOTE (US-517); почему не на пути рана — docs/18, Д41. */
+/** QUOTE path only: a raw voice id is checked at run start, not at quote time. */
 export const RAW_VOICE_ID_VALIDATION_WARNING = "raw voice_id is verified against your account at run start, not at quote time";
-/**
- * Голосовые warnings по ТЕСТУ ДОПУСТИМОСТИ (план §Р3). Warning допустим, только
- * если ОДНОВРЕМЕННО: (i) причина — то, что клиент запросил ЯВНО (не дефолт, не наш
- * выбор); (ii) утверждение опирается на данные, которые ЕСТЬ (лейбл присутствует),
- * а не на их отсутствие; (iii) на дефолтном happy-path не срабатывает НИКОГДА.
- *
- * ПРАВИЛО СТАРШИНСТВА ПОДМЕНЫ: подмена (клиент попросил X, отдали Y) предупреждает
- * ВСЕГДА, независимо от (iii) — (iii) глушит уведомления о ПРАВИЛЬНОМ поведении, не
- * о деградированном. Канон такой подмены — 1080p→720p (render-backend.ts:144). В
- * ДАННОМ дизайне подмены голоса НЕТ: путь падает closed (сырой id не найден → бросок
- * до платного POST, US-515; неизвестное имя → 400 на границе enum), голос молча не
- * заменяется. Поэтому правило старшинства здесь не применяется — но зафиксировано,
- * чтобы будущая подмена не была ошибочно заглушена условием (iii).
- *
- * ПОЧЕМУ тест не подавляет обязательный warning про подмену №3 (принцип DR-2):
- * обязанность №3 крепится к НЕИСПОЛНЕННОМУ явному запросу (клиент попросил 1080p,
- * дали 720p) — это подмена, у неё старшинство над (iii). Здесь же голос либо
- * исполняется как запрошен, либо ран падает — деградированной выдачи под видом
- * успешной не бывает, глушить нечего.
- */
+/** Voice warnings fire only when (i) the client chose explicitly, (ii) the claim rests on data */
+/** present, (iii) never on the default happy path. A voice is never substituted, only failed. */
 export function buildVoiceWarnings(input) {
-    // Сырой escape-hatch id: причина явная (i), но проверка существования отложена
-    // до рана. На quote префлайта нет — предупреждаем об отложенной валидации.
+    // A raw id is an explicit choice, but its existence is checked at run start,
+    // so the quote warns about deferred validation.
     if (input.voice_id !== undefined) {
         return [RAW_VOICE_ID_VALIDATION_WARNING];
     }
-    // Условие (iii): голос не задан явно → языковых warning'ов нет никогда (анти-шум US-517).
-    // Голос по полу актёра обсуждает `buildActorGenderWarnings` (actors.ts).
+    // No explicit voice: no language warnings ever. The gender-based voice is
+    // covered by `buildActorGenderWarnings` (actors.ts).
     if (input.voice === undefined) {
         return [];
     }
-    // Defensive: до вызова zod уже сузил voice до валидного имени enum, но чистая
-    // функция не полагается на это. Неизвестное имя → нет пресета → нет данных → [].
+    // Defensive: zod already narrowed voice, but a pure function does not rely on it.
+    // An unknown name has no preset and so no data.
     if (!isVoicePresetName(input.voice)) {
         return [];
     }
     const preset = VOICE_PRESETS[input.voice];
-    // Условие (ii): сравнивать можно только при ПРИСУТСТВУЮЩЕМ пригодном лейбле.
-    // Язык вне размеченного набора (ru/en) — «нет данных» → молчим, не выдумываем.
+    // Compare only against a PRESENT usable label; a language outside ru/en means
+    // no data, so stay silent instead of guessing.
     const voiceFamily = LANGUAGE_TO_SCRIPT_FAMILY[preset.language];
     if (voiceFamily === undefined) {
         return [];
     }
-    // Условие (i)+(ii) выполнены: причина — явно выбранный пресет, а суждение
-    // опирается на присутствующий лейбл против ДЕТЕКТИРОВАННОГО семейства скрипта.
-    // Нейтральный/неоднозначный скрипт не противоречит ничему → молчим (ii).
+    // An explicit preset against the detected script family. A neutral or mixed
+    // script contradicts nothing.
     const scriptFamily = detectScriptFamily(input.script);
     if (scriptFamily === "neutral" || scriptFamily === voiceFamily) {
         return [];
     }
-    // «БУКВ НЕТ ВОВСЕ» И «НЕ ТОТ ЯЗЫК» — РАЗНЫЕ СОВЕТЫ ЧИТАТЕЛЮ (clipwright#131):
-    // первое чинят текстом или доставкой, второе — выбором голоса.
+    // "No letters at all" and "wrong language" call for different fixes: the text or
+    // its delivery versus the voice choice.
     const counts = scriptLetterCounts(input.script);
     if (counts[voiceFamily] === 0) {
         return [
@@ -321,12 +278,12 @@ export function buildVoiceWarnings(input) {
         `voice "${input.voice}" is labeled ${preset.language}, but the script looks ${scriptFamily}; it will be voiced in a ${preset.language} voice`,
     ];
 }
-/** Модель, не читающая ударения, на тексте, где они важны. На умолчании (v3) молчит всегда. */
+/** A model that ignores stress marks on text where they matter. Silent on the v3 default. */
 export function buildSpeechModelWarnings(input, gender) {
     const model = resolveTtsModel(input, gender);
     if (STRESS_MARK_MODELS.has(model))
         return [];
-    // Знак после латиницы — акцент французского или испанского текста (NFD), не ударение.
+    // A mark after a Latin letter is a French or Spanish accent (NFD), not stress.
     const marked = CYRILLIC_STRESS_MARK.test(input.script) || stressMarksFromCapitals(input.script) !== input.script;
     if (marked) {
         return [