@nodaro/shared 3.64.0 → 3.66.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (208) hide show
  1. package/dist/{chunk-J6B7J73J.cjs → chunk-23IKLMRL.cjs} +49 -49
  2. package/dist/{chunk-J6B7J73J.cjs.map → chunk-23IKLMRL.cjs.map} +1 -1
  3. package/dist/chunk-27HA6YOL.cjs +377 -0
  4. package/dist/chunk-27HA6YOL.cjs.map +1 -0
  5. package/dist/{chunk-OOZW2MM6.cjs → chunk-37ZSFS6A.cjs} +9 -9
  6. package/dist/{chunk-OOZW2MM6.cjs.map → chunk-37ZSFS6A.cjs.map} +1 -1
  7. package/dist/{chunk-AZNZ5WNZ.cjs → chunk-3L7GMQ4M.cjs} +142 -45
  8. package/dist/chunk-3L7GMQ4M.cjs.map +1 -0
  9. package/dist/{chunk-SXHHLZ22.js → chunk-3QJ3UR5Z.js} +9 -9
  10. package/dist/{chunk-SXHHLZ22.js.map → chunk-3QJ3UR5Z.js.map} +1 -1
  11. package/dist/chunk-3YWZ5SOZ.js +164 -0
  12. package/dist/chunk-3YWZ5SOZ.js.map +1 -0
  13. package/dist/{chunk-TTGZ2L3O.js → chunk-5GG4CG4Y.js} +3 -3
  14. package/dist/{chunk-TTGZ2L3O.js.map → chunk-5GG4CG4Y.js.map} +1 -1
  15. package/dist/{chunk-3KTWYYCN.js → chunk-5IZHECUP.js} +3 -3
  16. package/dist/{chunk-3KTWYYCN.js.map → chunk-5IZHECUP.js.map} +1 -1
  17. package/dist/{chunk-Q2Y4JHF7.js → chunk-5J2LIQYU.js} +5 -5
  18. package/dist/{chunk-Q2Y4JHF7.js.map → chunk-5J2LIQYU.js.map} +1 -1
  19. package/dist/{chunk-SHH2T4CR.js → chunk-5LWYX4GV.js} +3 -3
  20. package/dist/{chunk-SHH2T4CR.js.map → chunk-5LWYX4GV.js.map} +1 -1
  21. package/dist/{chunk-7AJGUI7L.cjs → chunk-5NVGKXJV.cjs} +34 -17
  22. package/dist/chunk-5NVGKXJV.cjs.map +1 -0
  23. package/dist/{chunk-D4KWNDPH.cjs → chunk-66QSUUB4.cjs} +12 -12
  24. package/dist/{chunk-D4KWNDPH.cjs.map → chunk-66QSUUB4.cjs.map} +1 -1
  25. package/dist/{chunk-KHH54GRP.cjs → chunk-6ET3KDO4.cjs} +15 -338
  26. package/dist/chunk-6ET3KDO4.cjs.map +1 -0
  27. package/dist/{chunk-ZI3QDUHO.js → chunk-AT53ZQUC.js} +3 -3
  28. package/dist/{chunk-ZI3QDUHO.js.map → chunk-AT53ZQUC.js.map} +1 -1
  29. package/dist/chunk-BMDOPJBP.cjs +185 -0
  30. package/dist/chunk-BMDOPJBP.cjs.map +1 -0
  31. package/dist/{chunk-PJJAZQVZ.js → chunk-BNR5FKL5.js} +3 -3
  32. package/dist/{chunk-PJJAZQVZ.js.map → chunk-BNR5FKL5.js.map} +1 -1
  33. package/dist/{chunk-5OBTGNUQ.cjs → chunk-E62W5I6A.cjs} +298 -2
  34. package/dist/chunk-E62W5I6A.cjs.map +1 -0
  35. package/dist/{chunk-GTWUS6MQ.cjs → chunk-EFYWV2V5.cjs} +61 -61
  36. package/dist/{chunk-GTWUS6MQ.cjs.map → chunk-EFYWV2V5.cjs.map} +1 -1
  37. package/dist/chunk-F6XIH3TZ.cjs +168 -0
  38. package/dist/chunk-F6XIH3TZ.cjs.map +1 -0
  39. package/dist/{chunk-NIAFR5EE.js → chunk-FGBGKBML.js} +32 -3
  40. package/dist/chunk-FGBGKBML.js.map +1 -0
  41. package/dist/{chunk-YQV53HRR.cjs → chunk-G2G7XGFU.cjs} +7 -7
  42. package/dist/{chunk-YQV53HRR.cjs.map → chunk-G2G7XGFU.cjs.map} +1 -1
  43. package/dist/{chunk-7KQ6W5DS.js → chunk-GF7ZA26H.js} +4 -4
  44. package/dist/{chunk-7KQ6W5DS.js.map → chunk-GF7ZA26H.js.map} +1 -1
  45. package/dist/{chunk-SPAHI7DY.cjs → chunk-GNLA5NTT.cjs} +4 -4
  46. package/dist/{chunk-SPAHI7DY.cjs.map → chunk-GNLA5NTT.cjs.map} +1 -1
  47. package/dist/{chunk-VPTA4Z7G.js → chunk-GTBW2KAY.js} +5 -5
  48. package/dist/{chunk-VPTA4Z7G.js.map → chunk-GTBW2KAY.js.map} +1 -1
  49. package/dist/{chunk-CHS2SIP6.cjs → chunk-HTDKEYMY.cjs} +90 -76
  50. package/dist/chunk-HTDKEYMY.cjs.map +1 -0
  51. package/dist/{chunk-EXEVT6D2.cjs → chunk-IWUW3YPM.cjs} +5 -5
  52. package/dist/{chunk-EXEVT6D2.cjs.map → chunk-IWUW3YPM.cjs.map} +1 -1
  53. package/dist/{chunk-ACZZHHFZ.cjs → chunk-JTYCJ5OL.cjs} +44 -22
  54. package/dist/chunk-JTYCJ5OL.cjs.map +1 -0
  55. package/dist/{chunk-HDPJNNMF.cjs → chunk-M5QY464F.cjs} +21 -21
  56. package/dist/{chunk-HDPJNNMF.cjs.map → chunk-M5QY464F.cjs.map} +1 -1
  57. package/dist/{chunk-DZ4IOP3Q.js → chunk-MVXZP6VB.js} +281 -3
  58. package/dist/chunk-MVXZP6VB.js.map +1 -0
  59. package/dist/{chunk-Y4GCJJPF.cjs → chunk-NYZQOIXJ.cjs} +35 -2
  60. package/dist/chunk-NYZQOIXJ.cjs.map +1 -0
  61. package/dist/{chunk-KB2SQAR3.js → chunk-OFQ6CU6S.js} +3 -3
  62. package/dist/{chunk-KB2SQAR3.js.map → chunk-OFQ6CU6S.js.map} +1 -1
  63. package/dist/{chunk-36VWLB4J.js → chunk-OXBU5AGH.js} +3 -3
  64. package/dist/{chunk-36VWLB4J.js.map → chunk-OXBU5AGH.js.map} +1 -1
  65. package/dist/{chunk-CHTZZRAL.cjs → chunk-OXTF4Y3P.cjs} +6 -6
  66. package/dist/{chunk-CHTZZRAL.cjs.map → chunk-OXTF4Y3P.cjs.map} +1 -1
  67. package/dist/{chunk-3AYM47GW.js → chunk-PAUWEWTY.js} +99 -9
  68. package/dist/chunk-PAUWEWTY.js.map +1 -0
  69. package/dist/{chunk-FHGRKQVZ.cjs → chunk-PGDR7CO3.cjs} +8 -8
  70. package/dist/{chunk-FHGRKQVZ.cjs.map → chunk-PGDR7CO3.cjs.map} +1 -1
  71. package/dist/{chunk-W6VJAUGM.cjs → chunk-PJAJCFLP.cjs} +94 -37
  72. package/dist/chunk-PJAJCFLP.cjs.map +1 -0
  73. package/dist/{chunk-IYSOVS7O.js → chunk-RVQW623D.js} +31 -13
  74. package/dist/chunk-RVQW623D.js.map +1 -0
  75. package/dist/{chunk-TPQJKS7D.js → chunk-SCDE676D.js} +21 -7
  76. package/dist/{chunk-CHS2SIP6.cjs.map → chunk-SCDE676D.js.map} +1 -1
  77. package/dist/chunk-SW5ZD7BO.js +143 -0
  78. package/dist/chunk-SW5ZD7BO.js.map +1 -0
  79. package/dist/{chunk-T2OVDF2M.cjs → chunk-T4GIHHXY.cjs} +6 -6
  80. package/dist/{chunk-T2OVDF2M.cjs.map → chunk-T4GIHHXY.cjs.map} +1 -1
  81. package/dist/{chunk-QYU7J5EQ.js → chunk-V6OXSXIX.js} +29 -18
  82. package/dist/chunk-V6OXSXIX.js.map +1 -0
  83. package/dist/{chunk-W7KHHNZR.js → chunk-VBP4DH37.js} +61 -9
  84. package/dist/chunk-VBP4DH37.js.map +1 -0
  85. package/dist/{chunk-67CMMTLN.cjs → chunk-WZG6GZIL.cjs} +4 -4
  86. package/dist/{chunk-67CMMTLN.cjs.map → chunk-WZG6GZIL.cjs.map} +1 -1
  87. package/dist/{chunk-O4RPXBDZ.cjs → chunk-X2YHKP4D.cjs} +8 -8
  88. package/dist/{chunk-O4RPXBDZ.cjs.map → chunk-X2YHKP4D.cjs.map} +1 -1
  89. package/dist/{chunk-OBOOHG3N.js → chunk-XEPKONJC.js} +3 -3
  90. package/dist/{chunk-OBOOHG3N.js.map → chunk-XEPKONJC.js.map} +1 -1
  91. package/dist/{chunk-O7RZRUMZ.js → chunk-XJWED257.js} +14 -309
  92. package/dist/chunk-XJWED257.js.map +1 -0
  93. package/dist/chunk-XSSLNINL.js +346 -0
  94. package/dist/chunk-XSSLNINL.js.map +1 -0
  95. package/dist/{chunk-4IUE2JB7.js → chunk-Z77M7Q2R.js} +3 -3
  96. package/dist/{chunk-4IUE2JB7.js.map → chunk-Z77M7Q2R.js.map} +1 -1
  97. package/dist/entries/apps.cjs +42 -42
  98. package/dist/entries/apps.js +7 -7
  99. package/dist/entries/captions.d.cts +1 -1
  100. package/dist/entries/captions.d.ts +1 -1
  101. package/dist/entries/credits.cjs +230 -214
  102. package/dist/entries/credits.d.cts +51 -14
  103. package/dist/entries/credits.d.ts +51 -14
  104. package/dist/entries/credits.js +10 -10
  105. package/dist/entries/entities.cjs +202 -193
  106. package/dist/entries/entities.d.cts +44 -9
  107. package/dist/entries/entities.d.ts +44 -9
  108. package/dist/entries/entities.js +2 -1
  109. package/dist/entries/llm-models.cjs +86 -62
  110. package/dist/entries/llm-models.d.cts +46 -15
  111. package/dist/entries/llm-models.d.ts +46 -15
  112. package/dist/entries/llm-models.js +2 -2
  113. package/dist/entries/media.cjs +79 -63
  114. package/dist/entries/media.d.cts +154 -1
  115. package/dist/entries/media.d.ts +154 -1
  116. package/dist/entries/media.js +1 -1
  117. package/dist/entries/model-catalog.cjs +175 -119
  118. package/dist/entries/model-catalog.d.cts +4 -54
  119. package/dist/entries/model-catalog.d.ts +4 -54
  120. package/dist/entries/model-catalog.js +4 -4
  121. package/dist/entries/models.cjs +503 -358
  122. package/dist/entries/models.d.cts +86 -7
  123. package/dist/entries/models.d.ts +86 -7
  124. package/dist/entries/models.js +6 -5
  125. package/dist/entries/nodes.cjs +212 -212
  126. package/dist/entries/nodes.d.cts +1 -1
  127. package/dist/entries/nodes.d.ts +1 -1
  128. package/dist/entries/nodes.js +8 -8
  129. package/dist/entries/pipeline.cjs +153 -153
  130. package/dist/entries/pipeline.d.cts +3 -3
  131. package/dist/entries/pipeline.d.ts +3 -3
  132. package/dist/entries/pipeline.js +3 -3
  133. package/dist/entries/social.cjs +177 -177
  134. package/dist/entries/social.js +2 -2
  135. package/dist/entries/ugc.cjs +71 -71
  136. package/dist/entries/ugc.js +4 -4
  137. package/dist/entries/video.cjs +174 -145
  138. package/dist/entries/video.d.cts +119 -2
  139. package/dist/entries/video.d.ts +119 -2
  140. package/dist/entries/video.js +7 -6
  141. package/dist/entries/workflow.d.cts +1 -1
  142. package/dist/entries/workflow.d.ts +1 -1
  143. package/dist/index.cjs +2086 -1793
  144. package/dist/index.d.cts +10 -9
  145. package/dist/index.d.ts +10 -9
  146. package/dist/index.js +24 -23
  147. package/dist/{model-catalog-Cf9fkEUp.d.ts → model-catalog-B-aQnUS8.d.cts} +186 -2
  148. package/dist/{model-catalog-Cf9fkEUp.d.cts → model-catalog-B-aQnUS8.d.ts} +186 -2
  149. package/dist/{model-constants-C_Nyft_i.d.cts → model-constants-BstsUup6.d.cts} +105 -6
  150. package/dist/{model-constants-BxjiWVQ9.d.ts → model-constants-DZ3tPGFO.d.ts} +105 -6
  151. package/dist/tts-capabilities-BJ4N8MIB.d.ts +133 -0
  152. package/dist/tts-capabilities-Cf_4nu1Z.d.cts +133 -0
  153. package/package.json +1 -1
  154. package/src/__tests__/dialogue-capabilities.test.ts +167 -6
  155. package/src/__tests__/extend-providers.test.ts +87 -0
  156. package/src/__tests__/flux-3-klein.test.ts +51 -3
  157. package/src/__tests__/image-run-limit.test.ts +96 -0
  158. package/src/__tests__/kling4-catalog.test.ts +1 -1
  159. package/src/__tests__/llm-models.test.ts +41 -4
  160. package/src/__tests__/seedream-5-5.test.ts +17 -0
  161. package/src/__tests__/speech-pricing.test.ts +62 -1
  162. package/src/__tests__/tts-capabilities.test.ts +160 -4
  163. package/src/__tests__/video-analysis-pricing.test.ts +13 -1
  164. package/src/__tests__/video-subjects.test.ts +209 -0
  165. package/src/__tests__/wired-character-names.test.ts +142 -0
  166. package/src/credit-estimators/index.ts +4 -0
  167. package/src/credit-estimators/speech.ts +57 -9
  168. package/src/credit-identifiers.ts +48 -13
  169. package/src/dialogue-capabilities.ts +220 -3
  170. package/src/dubbing-structure.ts +186 -0
  171. package/src/entries/entities.ts +2 -0
  172. package/src/entries/llm-models.ts +7 -0
  173. package/src/entries/media.ts +3 -1
  174. package/src/entries/model-catalog.ts +17 -0
  175. package/src/entries/models.ts +43 -0
  176. package/src/entries/video.ts +8 -1
  177. package/src/gemini-tts.ts +144 -0
  178. package/src/llm-models.ts +71 -21
  179. package/src/model-catalog.ts +283 -2
  180. package/src/model-constants.ts +167 -8
  181. package/src/tts-capabilities.ts +193 -1
  182. package/src/video-analysis-pricing.ts +11 -0
  183. package/src/video-character-refs.ts +165 -3
  184. package/src/wired-character-names.ts +134 -18
  185. package/src/wired-character-video-subjects.ts +63 -0
  186. package/dist/chunk-3AYM47GW.js.map +0 -1
  187. package/dist/chunk-5OBTGNUQ.cjs.map +0 -1
  188. package/dist/chunk-6YIV37V7.js +0 -31
  189. package/dist/chunk-6YIV37V7.js.map +0 -1
  190. package/dist/chunk-7AJGUI7L.cjs.map +0 -1
  191. package/dist/chunk-ACZZHHFZ.cjs.map +0 -1
  192. package/dist/chunk-AZNZ5WNZ.cjs.map +0 -1
  193. package/dist/chunk-DZ4IOP3Q.js.map +0 -1
  194. package/dist/chunk-IYSOVS7O.js.map +0 -1
  195. package/dist/chunk-KHH54GRP.cjs.map +0 -1
  196. package/dist/chunk-NIAFR5EE.js.map +0 -1
  197. package/dist/chunk-O7RZRUMZ.js.map +0 -1
  198. package/dist/chunk-QYU7J5EQ.js.map +0 -1
  199. package/dist/chunk-S3UGLZSF.js +0 -42
  200. package/dist/chunk-S3UGLZSF.js.map +0 -1
  201. package/dist/chunk-TPQJKS7D.js.map +0 -1
  202. package/dist/chunk-TQW3R44P.cjs +0 -38
  203. package/dist/chunk-TQW3R44P.cjs.map +0 -1
  204. package/dist/chunk-VZ6TE23U.cjs +0 -54
  205. package/dist/chunk-VZ6TE23U.cjs.map +0 -1
  206. package/dist/chunk-W6VJAUGM.cjs.map +0 -1
  207. package/dist/chunk-W7KHHNZR.js.map +0 -1
  208. package/dist/chunk-Y4GCJJPF.cjs.map +0 -1
@@ -13,7 +13,8 @@
13
13
  * text-to-speech request that names one runs as the fallback model, so these
14
14
  * helpers answer for the fallback there.
15
15
  */
16
- import { MODEL_CATALOG, type TtsCapabilities, type TtsSettingLever } from "./model-catalog.js"
16
+ import { MODEL_CATALOG, type TtsCapabilities, type TtsDirectionSheet, type TtsSettingLever } from "./model-catalog.js"
17
+ import { REPLICA_CONSENT_ATTESTATION, type TtsNamedVoice, type TtsReplica } from "./gemini-tts.js"
17
18
 
18
19
  /** Legacy provider ids that are another model under an old name. They have no catalog entry of their own. */
19
20
  export const TTS_PROVIDER_ALIASES: Readonly<Record<string, string>> = {
@@ -87,3 +88,194 @@ export function ttsSupportsTimestamps(provider: string | undefined): boolean {
87
88
  export function ttsLanguageCodes(provider: string | undefined): readonly string[] {
88
89
  return getTtsCapabilities(provider).languages
89
90
  }
91
+
92
+ /**
93
+ * The named voices the model speaks, or `undefined` when it speaks the
94
+ * ElevenLabs voices (premade, library, clones). See `TtsCapabilities.voices`.
95
+ */
96
+ export function ttsNamedVoices(provider: string | undefined): readonly TtsNamedVoice[] | undefined {
97
+ return getTtsCapabilities(provider).voices
98
+ }
99
+
100
+ /**
101
+ * Whether `voice` is one the model can speak: on a model with named voices,
102
+ * one of them by its exact wire name; on any other model, any id (the
103
+ * ElevenLabs voice checks apply there, as before).
104
+ */
105
+ export function ttsAcceptsVoice(provider: string | undefined, voice: string): boolean {
106
+ const named = ttsNamedVoices(provider)
107
+ return !named || named.some((v) => v.id === voice)
108
+ }
109
+
110
+ /**
111
+ * The voice a request on a named-voice model runs with: the one it names when
112
+ * the model speaks it, else the model's default. `undefined` on an ElevenLabs
113
+ * model (its own default applies downstream).
114
+ */
115
+ export function ttsNamedVoiceFor(provider: string | undefined, voice: unknown): string | undefined {
116
+ const caps = getTtsCapabilities(provider)
117
+ if (!caps.voices) return undefined
118
+ return typeof voice === "string" && caps.voices.some((v) => v.id === voice) ? voice : caps.defaultVoice
119
+ }
120
+
121
+ /** The style direction the model takes (`TtsCapabilities.direction`), or `undefined` when it takes none. */
122
+ export function ttsDirection(provider: string | undefined): TtsDirectionSheet | undefined {
123
+ return getTtsCapabilities(provider).direction
124
+ }
125
+
126
+ /** The model writes its tone tags `<in angle brackets>` from a closed list (`TtsCapabilities.tagSyntax`). */
127
+ export function ttsAngleTags(provider: string | undefined): readonly string[] | undefined {
128
+ const caps = getTtsCapabilities(provider)
129
+ return caps.audioTags && caps.tagSyntax === "angle" ? (caps.tags ?? []) : undefined
130
+ }
131
+
132
+ /**
133
+ * The style direction of a request, as the model takes it: each field kept
134
+ * only when the model's sheet names it and the value is one it accepts (a
135
+ * listed choice, or free text within its cap — trimmed, an empty one
136
+ * dropped). What the provider funnel sends and the workflow engine passes on;
137
+ * the REST route rejects instead of dropping (`ttsDirectionProblem`).
138
+ */
139
+ export interface TtsDirectionValues {
140
+ styleDirection?: string
141
+ pace?: string
142
+ accent?: string
143
+ audioProfile?: string
144
+ }
145
+
146
+ export function ttsDirectionFor(provider: string | undefined, values: Readonly<Record<string, unknown>>): TtsDirectionValues {
147
+ const sheet = ttsDirection(provider)
148
+ if (!sheet) return {}
149
+ const text = (value: unknown, max: number | undefined): string | undefined => {
150
+ if (max === undefined || typeof value !== "string") return undefined
151
+ const trimmed = value.trim()
152
+ return trimmed && trimmed.length <= max ? trimmed : undefined
153
+ }
154
+ const choice = (value: unknown, choices: readonly string[] | undefined): string | undefined =>
155
+ choices && typeof value === "string" && choices.includes(value) ? value : undefined
156
+ const out: TtsDirectionValues = {}
157
+ const style = sheet.styles ? choice(values.styleDirection, sheet.styles) : text(values.styleDirection, sheet.styleMaxChars)
158
+ if (style !== undefined) out.styleDirection = style
159
+ const pace = choice(values.pace, sheet.paces)
160
+ if (pace !== undefined) out.pace = pace
161
+ const accent = choice(values.accent, sheet.accents)
162
+ if (accent !== undefined) out.accent = accent
163
+ const profile = text(values.audioProfile, sheet.audioProfileMaxChars)
164
+ if (profile !== undefined) out.audioProfile = profile
165
+ return out
166
+ }
167
+
168
+ /**
169
+ * Why a request's style direction cannot run on the model, or `undefined`
170
+ * when it can. Only the fields the model takes are judged; on a model that
171
+ * takes none, or a field it does not take, the value is never sent (as the
172
+ * neighbour text on a model that does not stitch), so it is no problem.
173
+ */
174
+ export function ttsDirectionProblem(provider: string | undefined, values: Readonly<Record<string, unknown>>): { field: keyof TtsDirectionValues; message: string } | undefined {
175
+ const sheet = ttsDirection(provider)
176
+ if (!sheet) return undefined
177
+ const textProblem = (field: keyof TtsDirectionValues, max: number | undefined) => {
178
+ const value = values[field]
179
+ if (max === undefined || value === undefined) return undefined
180
+ if (typeof value !== "string") return { field, message: `${field} must be a string` }
181
+ return value.trim().length > max ? { field, message: `${field} must be at most ${max} characters` } : undefined
182
+ }
183
+ const choiceProblem = (field: keyof TtsDirectionValues, choices: readonly string[] | undefined) => {
184
+ const value = values[field]
185
+ if (!choices || value === undefined || value === "") return undefined
186
+ return typeof value === "string" && choices.includes(value) ? undefined : { field, message: `${field} must be one of: ${choices.join(", ")}` }
187
+ }
188
+ return (
189
+ (sheet.styles ? choiceProblem("styleDirection", sheet.styles) : textProblem("styleDirection", sheet.styleMaxChars)) ??
190
+ choiceProblem("pace", sheet.paces) ??
191
+ choiceProblem("accent", sheet.accents) ??
192
+ textProblem("audioProfile", sheet.audioProfileMaxChars)
193
+ )
194
+ }
195
+
196
+ /** Every voice name a named-voice model speaks (all of them, across models). Built once from the catalog. */
197
+ let namedVoiceIds: ReadonlySet<string> | undefined
198
+ function anyModelsNamedVoice(voice: string): boolean {
199
+ namedVoiceIds ??= new Set(
200
+ Object.values(MODEL_CATALOG).flatMap((m) => (m.modes.includes("tts") ? (m.tts?.voices ?? []).map((v) => v.id) : [])),
201
+ )
202
+ return namedVoiceIds.has(voice)
203
+ }
204
+
205
+ /**
206
+ * The voice a text-to-speech run on `provider` speaks, when the model and the
207
+ * voice may have been chosen apart — a published app's Model card, a field
208
+ * mapping onto the model, an upstream Character's voice, a preset's voice with
209
+ * a model the caller named (decided 2026-11-13: the editor's model-switch rule,
210
+ * applied wherever the editor is not there to apply it):
211
+ * - a model with named voices (Gemini): the voice when it is one of them, its
212
+ * default voice for any other voice, and none (its default) for none;
213
+ * - an ElevenLabs model: none (the deployment's default) for a voice that only
214
+ * a named-voice model speaks (`Fola`, `Kore`…), else the voice as given.
215
+ * Returns `undefined` for "no voice named"; never a voice the model refuses.
216
+ */
217
+ export function ttsVoiceForModel(provider: string | undefined, voice: unknown): string | undefined {
218
+ const named = typeof voice === "string" && voice.length > 0 ? voice : undefined
219
+ const caps = getTtsCapabilities(provider)
220
+ if (caps.voices) {
221
+ if (named === undefined) return undefined
222
+ return caps.voices.some((v) => v.id === named) ? named : caps.defaultVoice
223
+ }
224
+ return named !== undefined && anyModelsNamedVoice(named) ? undefined : named
225
+ }
226
+
227
+ /** The model clones a speaker's voice for one request (`TtsCapabilities.replica`: Gemini 3.8 Flash). */
228
+ export function ttsTakesReplica(provider: string | undefined): boolean {
229
+ return getTtsCapabilities(provider).replica === true
230
+ }
231
+
232
+ /** Every model that takes a one-off clone, in catalog order (for a refusal's sentence). */
233
+ export function replicaModels(): string[] {
234
+ return Object.values(MODEL_CATALOG).filter((m) => m.modes.includes("tts") && m.tts?.replica === true).map((m) => m.id)
235
+ }
236
+
237
+ /** Whether `value` is an https link (the only scheme a recording is fetched from). */
238
+ function isHttpsLink(value: unknown): value is string {
239
+ if (typeof value !== "string") return false
240
+ try {
241
+ return new URL(value).protocol === "https:"
242
+ } catch {
243
+ return false
244
+ }
245
+ }
246
+
247
+ /** A request's one-off clone as the platform reads it: two https links, or undefined when absent or not that shape. */
248
+ export function replicaOf(value: unknown): TtsReplica | undefined {
249
+ if (!value || typeof value !== "object") return undefined
250
+ const { sourceAudioUrl, consentAudioUrl } = value as Record<string, unknown>
251
+ return isHttpsLink(sourceAudioUrl) && isHttpsLink(consentAudioUrl) ? { sourceAudioUrl, consentAudioUrl } : undefined
252
+ }
253
+
254
+ /**
255
+ * Why a request's one-off clone (`replica`) cannot run on the model, or
256
+ * undefined (none asked, or one it takes). Refused, never dropped: a clone
257
+ * that is not sent is someone else's voice. The recordings themselves (WAV,
258
+ * size, length) are judged where they are fetched (backend
259
+ * `lib/voice-replica.ts`).
260
+ */
261
+ export function ttsReplicaProblem(provider: string | undefined, value: unknown): string | undefined {
262
+ if (value === undefined || value === null) return undefined
263
+ if (!ttsTakesReplica(provider)) {
264
+ return `${provider ?? "This model"} does not clone a voice; a one-off clone runs on ${replicaModels().join(", ")}`
265
+ }
266
+ return replicaOf(value) ? undefined : "replica needs sourceAudioUrl and consentAudioUrl, each an https link to a WAV recording"
267
+ }
268
+
269
+ /**
270
+ * Why an API or MCP clone lacks its consent, or undefined: a `replica` asked
271
+ * must say `consent: true` — the caller's confirmation of
272
+ * `REPLICA_CONSENT_ATTESTATION`, what the editor's checkbox says (decided
273
+ * 2026-11-13). Refused before anything is read or held.
274
+ */
275
+ export function replicaConsentProblem(value: unknown): string | undefined {
276
+ if (value === undefined || value === null) return undefined
277
+ return (value as { consent?: unknown }).consent === true
278
+ ? undefined
279
+ : `replica.consent must be true: it confirms "${REPLICA_CONSENT_ATTESTATION}"`
280
+ }
281
+
@@ -130,6 +130,11 @@ export const VIDEO_ANALYSIS_WINDOW = { LEN: WINDOW_LEN, STRIDE: WINDOW_STRIDE, O
130
130
  // regenerated, on the deployed 9_082 basis: the new gemini-3.8-flash family,
131
131
  // and `mixed` / `smart`, whose plans roll the fast model too. Every other row
132
132
  // is exactly as deployed.
133
+ //
134
+ // 2026-11-13 — the `ultra` tier (gemini-4-carbon) joined. Its four rows are new
135
+ // (migration 649); every other row is exactly as deployed. They are the decided
136
+ // schedule, set between `mixed` and `smart` in every bucket; the plugin's
137
+ // cost test holds its formula to them like every other row.
133
138
  export const VIDEO_ANALYSIS_BUCKET_CREDITS: Record<string, number> = {
134
139
  // Current fast tier (VIDEO_ANALYSIS_TIERS.fast, since 2026-11-13).
135
140
  "video-analysis:gemini-3.8-flash:60s": 186,
@@ -153,6 +158,12 @@ export const VIDEO_ANALYSIS_BUCKET_CREDITS: Record<string, number> = {
153
158
  "video-analysis:gemini-3.1-pro:180s": 232,
154
159
  "video-analysis:gemini-3.1-pro:360s": 640,
155
160
  "video-analysis:gemini-3.1-pro:600s": 1056,
161
+ // ULTRA (VIDEO_ANALYSIS_TIERS.ultra, since 2026-11-13) — the deepest-reasoning
162
+ // model reading every window. Above `mixed` and below `smart` per bucket.
163
+ "video-analysis:gemini-4-carbon:60s": 349,
164
+ "video-analysis:gemini-4-carbon:180s": 375,
165
+ "video-analysis:gemini-4-carbon:360s": 1054,
166
+ "video-analysis:gemini-4-carbon:600s": 1745,
156
167
  // Mixed tiers (`mixed` + `mixed-fast`) share ONE credit family — they are
157
168
  // variants of the same engine plan (plan internals live in the private
158
169
  // analysis plugin). Admin-tunable via model_pricing like every other row.
@@ -48,6 +48,17 @@ export interface VideoCharacterReference {
48
48
  * positive `voices` cap take it.
49
49
  */
50
50
  voice?: VideoCharacterVoice
51
+ /**
52
+ * A short single-shot clip of this character (public URL). On a model with a
53
+ * positive `videoCharacters` cap (Kling 4.0, Kling 4.0 Flash) the character
54
+ * becomes a VIDEO subject made from this clip instead of an image subject.
55
+ * The clip rides as one more reference video ({@link seatCharacterVideos}),
56
+ * so it is measured and capped as a reference video is; its own length must
57
+ * fit `VIDEO_CHARACTER_CLIP_DURATION_LIMITS`. It is priced like an image
58
+ * subject unless the model bills it as reference video
59
+ * ({@link pricedReferenceVideoUrls}). Any other model refuses it.
60
+ */
61
+ videoUrl?: string
51
62
  }
52
63
 
53
64
  /** Zod `.max()` ceiling for the wire field — the widest cap any provider declares. */
@@ -73,6 +84,148 @@ export function videoCharacterRefCap(provider: string | undefined): number {
73
84
  return provider ? (VIDEO_REF_LIMITS_BY_PROVIDER[provider]?.characters ?? 0) : 0
74
85
  }
75
86
 
87
+ /** How many characters may be VIDEO subjects (a `videoUrl` clip) on the provider; 0 = none. */
88
+ export function videoCharacterVideoCap(provider: string | undefined): number {
89
+ return provider ? (VIDEO_REF_LIMITS_BY_PROVIDER[provider]?.videoCharacters ?? 0) : 0
90
+ }
91
+
92
+ /** Every provider that takes video subjects, in declaration order. */
93
+ export function videoCharacterVideoProviders(): string[] {
94
+ return Object.entries(VIDEO_REF_LIMITS_BY_PROVIDER)
95
+ .filter(([, l]) => (l?.videoCharacters ?? 0) > 0)
96
+ .map(([id]) => id)
97
+ }
98
+
99
+ /** The clips a set of character references carries (`videoUrl`, trimmed, non-empty), in order. */
100
+ export function characterVideoUrls(
101
+ characterReferences: readonly unknown[] | undefined,
102
+ ): string[] {
103
+ const out: string[] = []
104
+ for (const c of characterReferences ?? []) {
105
+ const url = (c as { videoUrl?: unknown } | null | undefined)?.videoUrl
106
+ if (typeof url === "string" && url.trim()) out.push(url.trim())
107
+ }
108
+ return out
109
+ }
110
+
111
+ /**
112
+ * Whether the provider bills a character's video subject as reference-video
113
+ * seconds (`videoCharactersBillAsReferenceVideo`). False on every model today:
114
+ * Kling 4.0 and Kling 4.0 Flash, both measured, price a video subject like an
115
+ * image subject (decided 2026-11-14). A model that bills the clip declares the
116
+ * flag on its `VIDEO_REF_LIMITS_BY_PROVIDER` row.
117
+ */
118
+ export function videoCharacterClipsBilledAsReferenceVideo(provider: string | undefined): boolean {
119
+ return provider ? VIDEO_REF_LIMITS_BY_PROVIDER[provider]?.videoCharactersBillAsReferenceVideo === true : false
120
+ }
121
+
122
+ /**
123
+ * The reference videos a run is PRICED on: `referenceVideoUrls` as sent, less
124
+ * — on a model that does not bill video subjects as reference video
125
+ * ({@link videoCharacterClipsBilledAsReferenceVideo}) — the seats that are a
126
+ * character's clip. Those seats still count toward the model's video cap and
127
+ * the reference videos' total length (`seatCharacterVideos`, the duration
128
+ * check); they only leave the price. The same value when nothing leaves it.
129
+ * Every price path reads it: the routes' credit guard and `POST /v1/quote`,
130
+ * the workflow reservation, the estimates and the completion settlement.
131
+ */
132
+ export function pricedReferenceVideoUrls(args: {
133
+ provider: string | undefined
134
+ referenceVideoUrls: readonly unknown[] | undefined
135
+ characterReferences: readonly unknown[] | undefined
136
+ }): readonly unknown[] | undefined {
137
+ if (videoCharacterClipsBilledAsReferenceVideo(args.provider)) return args.referenceVideoUrls
138
+ const clips = new Set(characterVideoUrls(args.characterReferences))
139
+ if (clips.size === 0 || !args.referenceVideoUrls?.some((u) => typeof u === "string" && clips.has(u))) return args.referenceVideoUrls
140
+ return args.referenceVideoUrls.filter((u) => !(typeof u === "string" && clips.has(u)))
141
+ }
142
+
143
+ /** A refusal from {@link seatCharacterVideos}: a finished, user-facing sentence. */
144
+ export interface CharacterVideoSeatProblem {
145
+ code: "character_video_unsupported" | "character_videos_over_limit" | "character_video_shared" | "reference_videos_over_limit"
146
+ message: string
147
+ }
148
+
149
+ /**
150
+ * The reference-video list a run sends once its characters' clips are seated
151
+ * in it — the ONE rule both video routes (a precheck, before the duration
152
+ * check, the quote and any reservation) and the workflow run (the payload
153
+ * builder) apply, so a video subject's clip is measured and capped exactly as
154
+ * a reference video is (the provider counts both in one cap and one total
155
+ * length). The price reads the seated list through
156
+ * {@link pricedReferenceVideoUrls}, which leaves the clip out on a model that
157
+ * bills a video subject like an image subject. The provider runner then takes
158
+ * the seat back out of the reference videos and sends it as the character's
159
+ * subject.
160
+ *
161
+ * - No clip: the list as it came (the same value).
162
+ * - A clip already in the list (also wired as a plain reference video) keeps
163
+ * its seat, and becomes the subject only; any other is appended, in
164
+ * character order, after the reference videos.
165
+ * - Refused: a model that takes no video subjects; more clips than its
166
+ * `videoCharacters` cap; two characters with the same clip; reference
167
+ * videos plus clips over its `videos` cap (the provider counts both in one
168
+ * cap, and a clip past it would be neither measured nor sent).
169
+ * - On a model that takes video subjects (one shared cap), plain reference
170
+ * videos alone over that cap are refused too, instead of the extra ones
171
+ * being left out without a word (decided 2026-11-13). Any other model's
172
+ * list is not judged here.
173
+ */
174
+ export function seatCharacterVideos(args: {
175
+ provider: string | undefined
176
+ referenceVideoUrls: readonly unknown[] | undefined
177
+ characterReferences: readonly unknown[] | undefined
178
+ }):
179
+ | { ok: true; referenceVideoUrls: readonly unknown[] | undefined }
180
+ | ({ ok: false } & CharacterVideoSeatProblem) {
181
+ const clips = characterVideoUrls(args.characterReferences)
182
+ const provider = args.provider ?? "the selected model"
183
+ const cap = videoCharacterVideoCap(args.provider)
184
+ const videosCap = VIDEO_REF_LIMITS_BY_PROVIDER[args.provider as string]?.videos ?? 0
185
+ const overVideos = (count: number): { ok: false } & CharacterVideoSeatProblem => ({
186
+ ok: false,
187
+ code: "reference_videos_over_limit",
188
+ message:
189
+ `${provider} takes at most ${videosCap} videos in all — reference videos and characters made from a video together. ` +
190
+ `This run has ${count}. Remove a reference video${clips.length > 0 ? ", or the video from a character" : ""}.`,
191
+ })
192
+ if (clips.length === 0) {
193
+ const sent = (args.referenceVideoUrls ?? []).length
194
+ if (cap > 0 && sent > videosCap) return overVideos(sent)
195
+ return { ok: true, referenceVideoUrls: args.referenceVideoUrls }
196
+ }
197
+ if (cap === 0) {
198
+ const takers = videoCharacterVideoProviders()
199
+ return {
200
+ ok: false,
201
+ code: "character_video_unsupported",
202
+ message:
203
+ `A character video (characterReferences[].videoUrl) is not supported by ${provider}. ` +
204
+ `Models that take one: ${takers.join(", ")}. Otherwise drop the video and keep the character's images.`,
205
+ }
206
+ }
207
+ if (clips.length > cap) {
208
+ return {
209
+ ok: false,
210
+ code: "character_videos_over_limit",
211
+ message: `${provider} takes at most ${cap} characters made from a video; ${clips.length} characters carry one. Remove the video from some of them.`,
212
+ }
213
+ }
214
+ if (new Set(clips).size < clips.length) {
215
+ return {
216
+ ok: false,
217
+ code: "character_video_shared",
218
+ message: "Two characters carry the same video. Each character made from a video needs a clip of its own.",
219
+ }
220
+ }
221
+ // The list as sent stays as it is (an entry the route's schema would refuse
222
+ // is still there for it to refuse); the clips follow it.
223
+ const raw = args.referenceVideoUrls ?? []
224
+ const seated: unknown[] = [...raw, ...clips.filter((c) => !raw.includes(c))]
225
+ if (seated.length > videosCap) return overVideos(seated.length)
226
+ return { ok: true, referenceVideoUrls: seated }
227
+ }
228
+
76
229
  /** How many DISTINCT voice personas the provider takes per request; 0 = none. */
77
230
  export function videoCharacterVoiceCap(provider: string | undefined): number {
78
231
  return provider ? (VIDEO_REF_LIMITS_BY_PROVIDER[provider]?.voices ?? 0) : 0
@@ -278,13 +431,21 @@ export function videoCharacterRefProblem(args: {
278
431
  * image still yields a reference — the provider decides (Kling keeps it a
279
432
  * reference image).
280
433
  */
281
- export function characterReferencesFromWired(refs: readonly ConnectedReference[]): VideoCharacterReference[] {
282
- const bySlug = new Map<string, { name: string; description?: string; urls: string[] }>()
434
+ export function characterReferencesFromWired(
435
+ refs: readonly ConnectedReference[],
436
+ /**
437
+ * The clip each wired character carries, by its slug (`wiredCharacterVideoUrls`):
438
+ * pass it only for a model that takes video subjects. Absent = none.
439
+ */
440
+ videoBySlug?: ReadonlyMap<string, string>,
441
+ ): VideoCharacterReference[] {
442
+ const bySlug = new Map<string, { name: string; description?: string; urls: string[]; videoUrl?: string }>()
283
443
  for (const r of refs) {
284
444
  if (r.source !== "wired-character" || !r.characterSlug || !r.url) continue
285
445
  let entry = bySlug.get(r.characterSlug)
286
446
  if (!entry) {
287
- entry = { name: r.defaultName.split(" / ")[0]!.trim() || r.characterSlug, urls: [] }
447
+ const videoUrl = videoBySlug?.get(r.characterSlug)
448
+ entry = { name: r.defaultName.split(" / ")[0]!.trim() || r.characterSlug, urls: [], ...(videoUrl ? { videoUrl } : {}) }
288
449
  bySlug.set(r.characterSlug, entry)
289
450
  }
290
451
  const description = (r.characterCanonicalDescription ?? r.description)?.trim()
@@ -299,5 +460,6 @@ export function characterReferencesFromWired(refs: readonly ConnectedReference[]
299
460
  ...(c.urls.length > 1 ? { extraImageUrls: c.urls.slice(1, 1 + VIDEO_CHARACTER_EXTRA_IMAGES_MAX) } : {}),
300
461
  description: (c.description ?? c.name).slice(0, VIDEO_CHARACTER_DESCRIPTION_MAX),
301
462
  name: c.name.slice(0, VIDEO_CHARACTER_NAME_MAX),
463
+ ...(c.videoUrl ? { videoUrl: c.videoUrl } : {}),
302
464
  }))
303
465
  }
@@ -73,45 +73,109 @@ export interface WiredCharacterName {
73
73
  * unnamed ones: "Character 1", "Character 2", …, skipping a number whose
74
74
  * name (by slug) another wired character already has. Unnamed nodes are
75
75
  * never merged.
76
- * - A typed name the slug cannot spell ("マヤ", "מאיה", "마야" — no Latin
77
- * letter or digit) is a real name: the model reads it as typed, and the node
78
- * takes the next number of the same sequence as its key (`character-N`), so
79
- * it is included on every path and no two keys collide.
76
+ * - A typed name with a letter of another script ("マヤ", "מאיה", "마야",
77
+ * and a mixed one such as "マヤ1" or "マヤ A") is a real name: the model
78
+ * reads it as typed. Which character it is goes by the WHOLE name
79
+ * ({@link scriptNameKey}), never by the Latin part the slug can spell, so
80
+ * "マヤ1" and "レオ1" are two characters and "マヤ A" is not "A" (decided
81
+ * 2026-11-13). Two nodes with the same such name are ONE character, as two
82
+ * "Maya" nodes are (decided 2026-11-12).
83
+ * - Its mention key: the name's own slug when the name has one and no other
84
+ * wired character claims it ("マヤ A" alone stays `@a`); else — no slug
85
+ * ("マヤ"), or a slug another character also claims — the next number of
86
+ * the unnamed sequence (`character-N`), taken once per character, so it is
87
+ * included on every path and no two keys collide.
88
+ * - A name whose letters are all Latin is keyed by its slug, exactly as before
89
+ * ("Maya", "maya" and "MAYA" are one character).
80
90
  *
81
91
  * `sources` are the consuming node's incoming wires in edge-array order.
82
92
  */
83
93
  export function wiredCharacterNames(sources: readonly WiredCharacterSource[]): Map<string, WiredCharacterName> {
84
- const order: Array<{ key: string; own: string }> = []
94
+ const order: Array<{ key: string; own: string; identity: string; ownSlug: string }> = []
85
95
  const seen = new Set<string>()
86
96
  for (const s of sources) {
87
97
  if (seen.has(s.key) || resolveEffectiveSourceType(s.type, s.sourceHandle) !== "character") continue
88
98
  seen.add(s.key)
89
- order.push({ key: s.key, own: characterOwnName(s.data) })
99
+ const own = characterOwnName(s.data)
100
+ order.push({ key: s.key, own, identity: characterIdentity(own) ?? `node:${s.key}`, ownSlug: characterMentionSlug(own) })
90
101
  }
91
- const taken = new Set<string>()
92
- for (const { own } of order) {
93
- const slug = characterMentionSlug(own)
94
- if (slug) taken.add(slug)
102
+ // Every character that would go by each slug: a Latin name always keeps its
103
+ // own; another name keeps it only when it is the one character claiming it.
104
+ const claims = new Map<string, Set<string>>()
105
+ for (const { identity, ownSlug } of order) {
106
+ if (!ownSlug) continue
107
+ const set = claims.get(ownSlug) ?? new Set<string>()
108
+ set.add(identity)
109
+ claims.set(ownSlug, set)
95
110
  }
111
+ const keepsOwnSlug = (identity: string, ownSlug: string): boolean =>
112
+ !!ownSlug && (identity.startsWith(LATIN_IDENTITY) || claims.get(ownSlug)?.size === 1)
113
+ const taken = new Set<string>()
114
+ for (const { identity, ownSlug } of order) if (keepsOwnSlug(identity, ownSlug)) taken.add(ownSlug)
96
115
  const out = new Map<string, WiredCharacterName>()
116
+ /** A character (by identity) → the `character-N` its first node took. */
117
+ const numberedOf = new Map<string, string>()
97
118
  let next = 1
98
- for (const { key, own } of order) {
99
- const ownSlug = characterMentionSlug(own)
100
- if (ownSlug) {
119
+ for (const { key, own, identity, ownSlug } of order) {
120
+ if (keepsOwnSlug(identity, ownSlug)) {
101
121
  out.set(key, { name: own, slug: ownSlug, unnamed: false })
102
122
  continue
103
123
  }
124
+ const same = numberedOf.get(identity)
125
+ if (same) {
126
+ out.set(key, { name: own, slug: same, unnamed: false })
127
+ continue
128
+ }
104
129
  while (taken.has(numberedSlug(next))) next++
105
130
  const slug = numberedSlug(next)
106
131
  taken.add(slug)
132
+ numberedOf.set(identity, slug)
107
133
  out.set(key, own ? { name: own, slug, unnamed: false } : { name: `${UNNAMED_CHARACTER_NAME_PREFIX} ${next}`, slug, unnamed: true })
108
134
  next++
109
135
  }
110
136
  return out
111
137
  }
112
138
 
139
+ const LATIN_IDENTITY = "latin:"
140
+
141
+ /** A letter of a script other than Latin (accented Latin letters are Latin). */
142
+ const OTHER_SCRIPT_LETTER = /(?=\p{L})\P{Script=Latin}/u
143
+
144
+ /**
145
+ * Which character a typed name is — two names with the same identity are one
146
+ * character. A name whose letters are all Latin: its slug, exactly as before.
147
+ * Any other name with a letter or digit: the whole name ({@link scriptNameKey}).
148
+ * Undefined for no name, or one with no letter or digit at all ("!!!"): such a
149
+ * node is a character of its own.
150
+ */
151
+ function characterIdentity(name: string): string | undefined {
152
+ const slug = characterMentionSlug(name)
153
+ if (slug && !OTHER_SCRIPT_LETTER.test(name)) return `${LATIN_IDENTITY}${slug}`
154
+ const key = scriptNameKey(name)
155
+ return key ? `script:${key}` : undefined
156
+ }
157
+
113
158
  const numberedSlug = (n: number): string => characterMentionSlug(`${UNNAMED_CHARACTER_NAME_PREFIX} ${n}`)
114
159
 
160
+ /**
161
+ * When two typed names the slug cannot spell are the same name: the rule
162
+ * {@link characterMentionSlug} applies to a Latin name ("Maya", "maya" and
163
+ * "MAYA" are one; so are "Maya Lee" and "maya-lee"), over every script.
164
+ * Unicode NFKC (half-width "マヤ" is "マヤ", a decomposed Hangul syllable is the
165
+ * composed one), then case folded (Cyrillic "Мая" is "мая"), then every run of
166
+ * characters that are no letter, digit or combining mark is one separator.
167
+ * Marks stay: "ガ" is not "カ". "" for a name with no letter or digit at all
168
+ * ("!!!"), which never matches another.
169
+ */
170
+ function scriptNameKey(name: string): string {
171
+ return name
172
+ .normalize("NFKC")
173
+ .toUpperCase()
174
+ .toLowerCase()
175
+ .replace(/[^\p{L}\p{N}\p{M}]+/gu, "-")
176
+ .replace(/^-+|-+$/g, "")
177
+ }
178
+
115
179
  /**
116
180
  * The slugs an unnamed character's mentions were written with before it was
117
181
  * numbered: its default label's ("Character Asset") and the retired default's
@@ -175,20 +239,49 @@ export function wiredCharacterNamesOf(
175
239
  return wiredCharacterNames(sources)
176
240
  }
177
241
 
242
+ /**
243
+ * The slug a Character node goes by for the node it feeds: its slug in
244
+ * `names`; else — a node wired only by its plain `image` pip, which `names`
245
+ * leaves out — the slug of the wired character that is the same name (the
246
+ * same whole name is the same character, in any script); else a Latin name's
247
+ * own slug, when no wired character of another identity goes by it; else "".
248
+ */
249
+ export function wiredCharacterSlug(
250
+ names: ReadonlyMap<string, WiredCharacterName>,
251
+ nodeId: string,
252
+ data: unknown,
253
+ ): string {
254
+ const wired = names.get(nodeId)?.slug
255
+ if (wired) return wired
256
+ const own = characterOwnName(data)
257
+ const identity = characterIdentity(own)
258
+ if (!identity) return ""
259
+ // The wired character that IS this name (the same identity, in any script).
260
+ for (const n of names.values()) {
261
+ if (!n.unnamed && characterIdentity(n.name) === identity) return n.slug
262
+ }
263
+ // None: a Latin name still goes by its own slug — unless a wired character
264
+ // of ANOTHER identity goes by it ("A" beside a wired "マヤ A", decided
265
+ // 2026-11-13), which it must never be filed under.
266
+ if (!identity.startsWith(LATIN_IDENTITY)) return ""
267
+ const slug = characterMentionSlug(own)
268
+ for (const n of names.values()) if (n.slug === slug) return ""
269
+ return slug
270
+ }
271
+
178
272
  /**
179
273
  * The key a Character node's OWN elements (held prop, styling, …) are filed
180
274
  * under for the node it feeds, so they land on that character's identity
181
- * bullet: its slug in `names`; else — a node wired only by its plain `image`
182
- * pip, which `names` leaves out — its own name's slug (the same typed name is
183
- * the same character); else a key of its own that no character carries, so an
184
- * unnamed node's elements are never merged into another character's.
275
+ * bullet: the slug it goes by ({@link wiredCharacterSlug}); else a key of its
276
+ * own that no character carries, so an unnamed node's elements are never
277
+ * merged into another character's.
185
278
  */
186
279
  export function wiredCharacterKey(
187
280
  names: ReadonlyMap<string, WiredCharacterName>,
188
281
  nodeId: string,
189
282
  data: unknown,
190
283
  ): string {
191
- return names.get(nodeId)?.slug || characterMentionSlug(characterOwnName(data)) || `node:${nodeId}`
284
+ return wiredCharacterSlug(names, nodeId, data) || `node:${nodeId}`
192
285
  }
193
286
 
194
287
  /** The wired character whose slug is `slug`, if any (first in wire order). */
@@ -200,3 +293,26 @@ export function wiredCharacterBySlug(
200
293
  for (const [key, named] of names) if (named.slug === slug) return { key, named }
201
294
  return undefined
202
295
  }
296
+
297
+ /**
298
+ * The clip each Character node wired into `consumerId` carries as its VIDEO
299
+ * subject (its `subjectVideoUrl`, a short single-shot clip of the character),
300
+ * by the slug the node goes by ({@link wiredCharacterNamesOf}) — the key
301
+ * `characterReferencesFromWired` groups a character by. Two nodes that are one
302
+ * character (the same typed name) take the first node's clip, in wire order. A
303
+ * node wired only by its plain `image` pip is no character and gives none.
304
+ * Read it only for a model that takes video subjects.
305
+ */
306
+ export function wiredCharacterVideoUrls(
307
+ consumerId: string,
308
+ nodes: ReadonlyArray<{ readonly id: string; readonly type?: string | null; readonly data?: unknown }>,
309
+ edges: ReadonlyArray<{ readonly source: string; readonly target: string; readonly sourceHandle?: string | null }>,
310
+ ): Map<string, string> {
311
+ const byId = new Map(nodes.map((n) => [n.id, n] as const))
312
+ const out = new Map<string, string>()
313
+ for (const [id, named] of wiredCharacterNamesOf(consumerId, nodes, edges)) {
314
+ const clip = (byId.get(id)?.data as { subjectVideoUrl?: unknown } | undefined)?.subjectVideoUrl
315
+ if (typeof clip === "string" && clip.trim() && !out.has(named.slug)) out.set(named.slug, clip.trim())
316
+ }
317
+ return out
318
+ }