ssml-builder-js 2.13.0 → 2.15.0

package/dist/core.d.ts

@@ -188,6 +188,45 @@ interface BuildPartialSsmlOptions extends SsmlPartialContext {
 declare function buildPartialSsml(text: string, context?: SsmlPartialContext): string;
 declare function buildPartialSsml(options: BuildPartialSsmlOptions): string;
 
+interface SsmlTextNodeContext {
+    parentTag: string;
+    parentAttributes: Record<string, string>;
+    ancestorTags: string[];
+    path: string[];
+}
+interface SsmlSourceTextSegment {
+    text: string;
+    range: {
+        start: number;
+        end: number;
+    };
+    sourceNodePath: string[];
+}
+interface SsmlSourceMarker {
+    kind: "mark" | "bookmark";
+    name: string;
+    originalTextRange: {
+        start: number;
+        end: number;
+    };
+    sourceNodePath: string[];
+}
+interface SsmlSourceMap {
+    text: string;
+    segments: SsmlSourceTextSegment[];
+    markers: SsmlSourceMarker[];
+}
+interface MapSsmlTextNodesOptions {
+    /** Element names whose text should not be passed to the transform. */
+    skipTags?: readonly string[];
+    /** Decides whether an individual text node should be passed to the transform. */
+    filter?: (context: SsmlTextNodeContext) => boolean;
+}
+/** Returns decoded source text segments and marker locations with indexed SSML paths. */
+declare function getSsmlSourceMap(ssml: string): SsmlSourceMap;
+declare function extractSsmlText(ssml: string): string[];
+declare function mapSsmlTextNodes(ssml: string, transform: (text: string, context: SsmlTextNodeContext) => string | Promise<string>, options?: MapSsmlTextNodesOptions): Promise<string>;
+
 interface SsmlTextRange {
     start: number;
     end: number;
@@ -204,6 +243,12 @@ interface SsmlChunk {
     inheritedContext: SsmlChunkContext;
     containedMarks: string[];
     hasBackgroundAudio: boolean;
+    /** Best-effort path to the first source element represented by this chunk. */
+    sourceNodePath?: string[];
+    /** Exact source segments represented by this chunk, used for event mapping. */
+    sourceTextSegments?: SsmlSourceTextSegment[];
+    /** Exact marker locations represented by this chunk, used for bookmark mapping. */
+    sourceMarkers?: SsmlSourceMarker[];
 }
 interface SplitSsmlOptions {
     maxLength?: number;
@@ -226,21 +271,6 @@ interface SsmlValidationError {
 }
 declare function validateSsml(xmlString: string): SsmlValidationError | null;
 
-interface SsmlTextNodeContext {
-    parentTag: string;
-    parentAttributes: Record<string, string>;
-    ancestorTags: string[];
-    path: string[];
-}
-interface MapSsmlTextNodesOptions {
-    /** Element names whose text should not be passed to the transform. */
-    skipTags?: readonly string[];
-    /** Decides whether an individual text node should be passed to the transform. */
-    filter?: (context: SsmlTextNodeContext) => boolean;
-}
-declare function extractSsmlText(ssml: string): string[];
-declare function mapSsmlTextNodes(ssml: string, transform: (text: string, context: SsmlTextNodeContext) => string | Promise<string>, options?: MapSsmlTextNodesOptions): Promise<string>;
-
 interface ExtractSsmlTranslatableTextOptions {
     /** Element names whose descendants are not translation targets. */
     skipTags?: readonly string[];
@@ -316,8 +346,17 @@ interface AzureValidationOptions {
     customVoiceDefinitions?: readonly AzureVoiceDefinition[];
     /** Host-side validation hook for URL-bearing SSML attributes. */
     urlValidator?: AzureUrlValidator;
+    /** Source path associated with a chunk being validated. */
+    sourceNodePath?: readonly string[];
     /** Alias for urlValidator retained for applications that use the longer name. */
     customUrlValidator?: AzureUrlValidator;
+    /** Controls deduplication, caching, cancellation, and concurrency for URL checks. */
+    urlValidation?: AzureUrlValidationRunnerOptions;
+    /** Flat aliases retained for callers that prefer not to nest URL runner options. */
+    urlValidatorConcurrency?: number;
+    urlValidatorTimeoutMs?: number;
+    urlValidatorSignal?: AbortSignal;
+    urlValidatorCache?: Map<string, AzureUrlValidationResult>;
     languageAliases?: Record<string, string | readonly string[]>;
     maxLength?: number;
     /** Maximum XML element nesting depth, counting `<speak>` as depth 1. */
@@ -344,7 +383,16 @@ type AzureUrlValidationResult = boolean | {
 type AzureUrlValidator = (url: string, context: {
     tag: string;
     attribute: string;
-}) => AzureUrlValidationResult | Promise<AzureUrlValidationResult>;
+    sourceNodePath?: readonly string[];
+}, signal: AbortSignal) => AzureUrlValidationResult | Promise<AzureUrlValidationResult>;
+interface AzureUrlValidationRunnerOptions {
+    concurrency?: number;
+    cache?: Map<string, AzureUrlValidationResult>;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+/** Wraps a URL validator with URL deduplication, bounded concurrency, caching, and cancellation. */
+declare function createAzureUrlValidatorRunner(validator: AzureUrlValidator, options?: AzureUrlValidationRunnerOptions): AzureUrlValidator;
 type AzureLanguageNormalizationOptions = Pick<AzureValidationOptions, "languageAliases" | "normalizeLanguage">;
 /** @deprecated Use AzureValidationOptions instead. */
 type AzureSsmlValidationOptions = AzureValidationOptions;
@@ -376,4 +424,4 @@ declare function getAzureVoiceCatalogMetadata(): AzureVoiceCatalogMetadata;
 /** Alias for consumers that refer to the bundled catalog as the built-in catalog. */
 declare const getBuiltInVoiceCatalogMetadata: typeof getAzureVoiceCatalogMetadata;
 
-export { type AudioElement, type AzureDiagnosticCode, type AzureLanguageNormalizationOptions, type AzureSsmlValidationOptions, type AzureUrlValidationResult, type AzureUrlValidator, type AzureValidationOptions, type AzureVoiceCatalogMetadata, type AzureVoiceDefinition, type AzureVoiceMetadata, type BookmarkElement, type BreakElement, type BuildPartialSsmlOptions, type CustomElement, type EmphasisElement, type ExpressAsElement, type ExtractSsmlTranslatableTextOptions, type FromPlainTextToSsmlOptions, type LangElement, type LexiconElement, type MapSsmlTextNodesOptions, type MarkElement, type MsttsAudioDurationElement, type MsttsEmbeddingElement, type MsttsSilenceElement, type MsttsTtsEmbeddingElement, type MsttsVisemeElement, type MsttsVoiceConversionElement, type NamedElement, type ParagraphElement, type PhonemeElement, type ProsodyElement, type SayAsElement, type SentenceElement, type SplitSsmlOptions, type SsmlAttributeValue, type SsmlAttributes, type SsmlBackgroundAudioNode, type SsmlBreakElement, type SsmlChunk, type SsmlChunkContext, type SsmlDiagnostic, type SsmlDiagnosticSeverity, type SsmlDiagnosticSource, type SsmlDialogNode, type SsmlDocument, type SsmlElement, type SsmlElementBase, type SsmlEmbeddingNode, type SsmlExpressAsElement, type SsmlNode, type SsmlPartialContext, type SsmlPartialProsody, type SsmlPartialVoice, type SsmlPhonemeElement, type SsmlProsodyElement, type SsmlSayAsElement, type SsmlStructureIntegrityResult, type SsmlStructureMismatch, type SsmlText, type SsmlTextNodeContext, type SsmlTextRange, type SsmlTtsEmbeddingNode, type SsmlTurnNode, type SsmlValidationError, type SsmlVoiceConversionNode, type SsmlVoiceElement, type SubElement, type VoiceElement, type WordElement, areAzureLanguagesEquivalent, buildPartialSsml, buildSsml, extractSsmlText, extractSsmlTranslatableText, fromPlainTextToSsml, getAzureVoiceCatalogMetadata, getBuiltInVoiceCatalogMetadata, isValidAzureAudioDuration, mapSsmlTextNodes, normalizeAzureLanguage, parseSsml, splitSsmlDocument, validateAzureSsml, validateSsml, validateSsmlStructureIntegrity };
+export { type AudioElement, type AzureDiagnosticCode, type AzureLanguageNormalizationOptions, type AzureSsmlValidationOptions, type AzureUrlValidationResult, type AzureUrlValidationRunnerOptions, type AzureUrlValidator, type AzureValidationOptions, type AzureVoiceCatalogMetadata, type AzureVoiceDefinition, type AzureVoiceMetadata, type BookmarkElement, type BreakElement, type BuildPartialSsmlOptions, type CustomElement, type EmphasisElement, type ExpressAsElement, type ExtractSsmlTranslatableTextOptions, type FromPlainTextToSsmlOptions, type LangElement, type LexiconElement, type MapSsmlTextNodesOptions, type MarkElement, type MsttsAudioDurationElement, type MsttsEmbeddingElement, type MsttsSilenceElement, type MsttsTtsEmbeddingElement, type MsttsVisemeElement, type MsttsVoiceConversionElement, type NamedElement, type ParagraphElement, type PhonemeElement, type ProsodyElement, type SayAsElement, type SentenceElement, type SplitSsmlOptions, type SsmlAttributeValue, type SsmlAttributes, type SsmlBackgroundAudioNode, type SsmlBreakElement, type SsmlChunk, type SsmlChunkContext, type SsmlDiagnostic, type SsmlDiagnosticSeverity, type SsmlDiagnosticSource, type SsmlDialogNode, type SsmlDocument, type SsmlElement, type SsmlElementBase, type SsmlEmbeddingNode, type SsmlExpressAsElement, type SsmlNode, type SsmlPartialContext, type SsmlPartialProsody, type SsmlPartialVoice, type SsmlPhonemeElement, type SsmlProsodyElement, type SsmlSayAsElement, type SsmlSourceMap, type SsmlSourceMarker, type SsmlSourceTextSegment, type SsmlStructureIntegrityResult, type SsmlStructureMismatch, type SsmlText, type SsmlTextNodeContext, type SsmlTextRange, type SsmlTtsEmbeddingNode, type SsmlTurnNode, type SsmlValidationError, type SsmlVoiceConversionNode, type SsmlVoiceElement, type SubElement, type VoiceElement, type WordElement, areAzureLanguagesEquivalent, buildPartialSsml, buildSsml, createAzureUrlValidatorRunner, extractSsmlText, extractSsmlTranslatableText, fromPlainTextToSsml, getAzureVoiceCatalogMetadata, getBuiltInVoiceCatalogMetadata, getSsmlSourceMap, isValidAzureAudioDuration, mapSsmlTextNodes, normalizeAzureLanguage, parseSsml, splitSsmlDocument, validateAzureSsml, validateSsml, validateSsmlStructureIntegrity };