ssml-builder-js 2.14.0 → 2.16.0

package/dist/core.d.mts

@@ -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;
@@ -206,6 +245,10 @@ interface SsmlChunk {
     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;
@@ -228,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[];
@@ -295,7 +323,21 @@ interface SsmlDiagnostic {
     message: string;
     severity: SsmlDiagnosticSeverity;
     source: SsmlDiagnosticSource;
+    /** Structured location and source metadata; message parsing is not required. */
+    targetNodePath?: string[];
+    /** Alias retained for callers using the shorter terminology. */
+    nodePath?: string[];
+    range?: {
+        start: number;
+        end: number;
+    };
+    tagName?: string;
+    attributeName?: string;
+    voiceName?: string;
+    chunkIndex?: number;
 }
+/** Generic name for a structured SSML diagnostic. */
+type Diagnostic = SsmlDiagnostic;
 interface AzureVoiceDefinition {
     name: string;
     locale: string;
@@ -318,6 +360,9 @@ 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[];
+    chunkIndex?: number;
     /** Alias for urlValidator retained for applications that use the longer name. */
     customUrlValidator?: AzureUrlValidator;
     /** Controls deduplication, caching, cancellation, and concurrency for URL checks. */
@@ -327,6 +372,8 @@ interface AzureValidationOptions {
     urlValidatorTimeoutMs?: number;
     urlValidatorSignal?: AbortSignal;
     urlValidatorCache?: Map<string, AzureUrlValidationResult>;
+    /** Shared runner used by chunk orchestration to deduplicate in-flight checks. */
+    urlValidatorRunner?: AzureUrlValidator;
     languageAliases?: Record<string, string | readonly string[]>;
     maxLength?: number;
     /** Maximum XML element nesting depth, counting `<speak>` as depth 1. */
@@ -353,7 +400,8 @@ 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>;
@@ -380,6 +428,8 @@ declare function validateAzureSsml(ssml: string, options: AzureValidationOptions
     urlValidator?: AzureUrlValidator;
     customUrlValidator?: AzureUrlValidator;
 }): SsmlDiagnostic[] | Promise<SsmlDiagnostic[]>;
+/** Validates multiple SSML chunks with one shared URL cache, semaphore, and in-flight pool. */
+declare function validateAzureSsmlChunks(chunks: readonly string[], options?: AzureValidationOptions): Promise<SsmlDiagnostic[][]>;
 
 interface AzureVoiceCatalogMetadata {
     apiVersion: string;
@@ -393,4 +443,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 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 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, 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 Diagnostic, 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, validateAzureSsmlChunks, validateSsml, validateSsmlStructureIntegrity };

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;
@@ -206,6 +245,10 @@ interface SsmlChunk {
     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;
@@ -228,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[];
@@ -295,7 +323,21 @@ interface SsmlDiagnostic {
     message: string;
     severity: SsmlDiagnosticSeverity;
     source: SsmlDiagnosticSource;
+    /** Structured location and source metadata; message parsing is not required. */
+    targetNodePath?: string[];
+    /** Alias retained for callers using the shorter terminology. */
+    nodePath?: string[];
+    range?: {
+        start: number;
+        end: number;
+    };
+    tagName?: string;
+    attributeName?: string;
+    voiceName?: string;
+    chunkIndex?: number;
 }
+/** Generic name for a structured SSML diagnostic. */
+type Diagnostic = SsmlDiagnostic;
 interface AzureVoiceDefinition {
     name: string;
     locale: string;
@@ -318,6 +360,9 @@ 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[];
+    chunkIndex?: number;
     /** Alias for urlValidator retained for applications that use the longer name. */
     customUrlValidator?: AzureUrlValidator;
     /** Controls deduplication, caching, cancellation, and concurrency for URL checks. */
@@ -327,6 +372,8 @@ interface AzureValidationOptions {
     urlValidatorTimeoutMs?: number;
     urlValidatorSignal?: AbortSignal;
     urlValidatorCache?: Map<string, AzureUrlValidationResult>;
+    /** Shared runner used by chunk orchestration to deduplicate in-flight checks. */
+    urlValidatorRunner?: AzureUrlValidator;
     languageAliases?: Record<string, string | readonly string[]>;
     maxLength?: number;
     /** Maximum XML element nesting depth, counting `<speak>` as depth 1. */
@@ -353,7 +400,8 @@ 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>;
@@ -380,6 +428,8 @@ declare function validateAzureSsml(ssml: string, options: AzureValidationOptions
     urlValidator?: AzureUrlValidator;
     customUrlValidator?: AzureUrlValidator;
 }): SsmlDiagnostic[] | Promise<SsmlDiagnostic[]>;
+/** Validates multiple SSML chunks with one shared URL cache, semaphore, and in-flight pool. */
+declare function validateAzureSsmlChunks(chunks: readonly string[], options?: AzureValidationOptions): Promise<SsmlDiagnostic[][]>;
 
 interface AzureVoiceCatalogMetadata {
     apiVersion: string;
@@ -393,4 +443,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 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 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, 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 Diagnostic, 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, validateAzureSsmlChunks, validateSsml, validateSsmlStructureIntegrity };