keepwork-sdk 1.0.0

package/dist-npm/types/src/ai-chat/SandboxToolEnv.d.ts

@@ -0,0 +1,210 @@
+/**
+ * SandboxToolEnv.ts — 工具沙箱执行环境（TypeScript 版）
+ *
+ * 为 AI 会话提供一个受控的工具执行上下文，包含：
+ * - `copilot` 代理对象：通过属性访问调用任意已注册工具
+ * - `processTemplate()`：展开 `${...}` 模板表达式
+ * - `registerAPI()`：注册自定义 API（优先于 CopilotTools）
+ * - 工具代理路由（toolProxy）：将指定工具委托给远程 agent
+ * - 远程 agent 模式（remoteAgent）：所有工具调用发往远程 agent
+ *
+ * ## 使用示例
+ * ```ts
+ * const sandbox = new SandboxToolEnv(sdk, {
+ *   workspace: 'myApp',
+ *   enabledCategories: ['fileOps', 'execute', 'agent'],
+ * });
+ * sandbox.registerAPI('get_weather', async (city) => fetchWeather(city));
+ * const expanded = await sandbox.processTemplate(
+ *   'Current time: ${new Date().toLocaleString()}'
+ * );
+ * ```
+ */
+/**
+ * 由 `copilot.restartAgent()` 在 `processTemplate()` 内部抛出的哨兵错误。
+ * 调用方（如 DigitalHuman._sendViaText）捕获此信号后触发 agent 会话重启。
+ */
+export declare class RestartAgentSignal {
+    readonly promptFile: string | null | undefined;
+    readonly tools: string[] | undefined;
+    readonly options: Record<string, unknown> | undefined;
+    /** 便于跨 iframe 传递时识别此信号类型 */
+    readonly isRestartAgentSignal = true;
+    /**
+     * @param promptFile - 新会话要加载的配置文件 URL 或路径（null/undefined 表示使用默认）
+     * @param tools      - 新会话启用的工具分类列表（undefined 表示继承）
+     * @param options    - 高级重启选项（minigameSlot / frameOptions 等）
+     */
+    constructor(promptFile?: string | null, tools?: string[], options?: Record<string, unknown>);
+}
+/** 工具代理路由配置 */
+export interface ToolProxyRoute {
+    /** 目标 agent 名称 */
+    agent: string;
+    /** 可选：任务描述 */
+    task?: string;
+}
+/** SandboxToolEnv 构造选项 */
+export interface SandboxToolEnvOptions {
+    /** 文件操作工作空间名（对应 personalPageStore 的 workspace 参数） */
+    workspace?: string;
+    /** 只读回退目录（挂载的外部公开文件夹） */
+    mountFolder?: unknown;
+    /** 启用的 CopilotTools 分类（默认 ['fileOps', 'execute']） */
+    enabledCategories?: string[];
+    /** 远程 agent 名称（设置后所有工具调用委托给该 agent） */
+    remoteAgent?: string;
+    /** 远程模式下授权的工具分类列表 */
+    categories?: string[];
+    /** 工具代理路由配置 */
+    toolProxy?: {
+        /** 按函数名代理：`{ 'read_file': { agent: 'fileAgent' } }` */
+        functions?: Record<string, ToolProxyRoute>;
+        /** 按分类代理：`{ 'fileOps': { agent: 'fileAgent' } }` */
+        categories?: Record<string, ToolProxyRoute>;
+    };
+    /** 关联的 ChatSession（允许工具通过 config._session 访问） */
+    session?: AgentSessionRef;
+}
+/** ChatSession 最小接口（避免循环引用） */
+interface AgentSessionRef {
+    name?: string;
+    workspace?: string;
+    _restartSignal?: unknown;
+    sandbox?: unknown;
+    [key: string]: unknown;
+}
+/** SDK 最小接口 */
+interface SDKRef {
+    copilotTools?: {
+        execute: (name: string, args: unknown, config: unknown) => Promise<unknown>;
+        getToolDefinitions: (categories: string[]) => unknown[];
+        _fnNameToCategory?: Record<string, string>;
+        _registry?: Record<string, {
+            disableAutoProxy?: boolean;
+        }>;
+    };
+    agentRouter?: {
+        hasAgent: (name: string) => boolean;
+        waitForAgent: (name: string) => Promise<void>;
+        submitTask: (name: string, payload: unknown) => Promise<unknown>;
+    };
+}
+declare class SandboxToolEnv {
+    readonly sdk: SDKRef;
+    workspace: string;
+    mountFolder: unknown;
+    enabledCategories: string[];
+    session: AgentSessionRef | null;
+    remoteAgent: string | null;
+    categories: string[];
+    _activePromptFile: string | null;
+    _templateSourceFile: string | null;
+    private _customAPIs;
+    private _copilotProxy;
+    private _toolProxy;
+    private _cachedDefinitions;
+    constructor(sdk: SDKRef, options?: SandboxToolEnvOptions);
+    /**
+     * copilot 代理对象：通过属性访问（如 `copilot.read_file(...)`）调用任意工具。
+     * 解析顺序：自定义 API → 工具代理（toolProxy）→ CopilotTools 内置工具。
+     */
+    get copilot(): Record<string, (...args: unknown[]) => Promise<string>>;
+    /**
+     * 注册自定义可调用 API（优先于同名 CopilotTools 工具）。
+     * 注册后 `copilot.myTool(args)` 将直接调用此函数。
+     *
+     * @param name - 工具/函数名称
+     * @param fn   - 异步回调函数 `(...args) => result`
+     */
+    registerAPI(name: string, fn: (...args: unknown[]) => Promise<unknown>): void;
+    /**
+     * 执行指定工具。
+     * - 远程 agent 模式：委托给 remoteAgent
+     * - 自定义 API：直接调用
+     * - 工具代理：通过 AgentRouter 路由到远程 agent
+     * - 内置工具：调用 sdk.copilotTools.execute
+     *
+     * @param fnName     - 工具/函数名称
+     * @param fnArgs     - 参数对象
+     * @param extraConfig - 附加配置（如 { _session }）
+     */
+    execute(fnName: string, fnArgs: unknown, extraConfig?: Record<string, unknown>): Promise<unknown>;
+    /**
+     * 获取已启用分类的 OpenAI 格式工具定义。
+     * 远程 agent 模式下从远端获取（带缓存）。
+     *
+     * @param forceRefresh - 是否强制刷新远程缓存（默认 false）
+     */
+    getToolDefinitions(forceRefresh?: boolean): Promise<unknown[]> | unknown[];
+    /** 检查沙箱是否可用（远程模式下检查 agent 是否已连接）。 */
+    isAvailable(): boolean;
+    /** 从远程 agent 获取所有可用工具分类列表。 */
+    getCategories(): Promise<unknown>;
+    /**
+     * 批量顺序执行工具调用，收集所有结果。
+     *
+     * @param calls - 工具调用列表 `[{ tool, args }]`
+     */
+    executeBatch(calls?: Array<{
+        tool: string;
+        args?: unknown;
+    }>): Promise<Array<{
+        tool: string;
+        success: boolean;
+        result?: unknown;
+        error?: string;
+    }>>;
+    /** 清除远程工具定义缓存。 */
+    clearCache(): void;
+    /**
+     * 在沙箱上下文中运行任意 async JavaScript 代码。
+     * 代码可访问 `copilot` 代理和 `context` 中的所有键。
+     *
+     * @param code    - 要执行的 JavaScript 代码字符串
+     * @param context - 注入到执行上下文的变量映射
+     */
+    runCode(code: string, context?: Record<string, unknown>): Promise<unknown>;
+    /**
+     * 展开文本中的 `${...}` 模板表达式。
+     * 表达式可使用 `copilot` 代理和 `await`。
+     * 支持最多 3 层嵌套递归展开。
+     * 表达式执行出错时保留原始 `${...}` 标记不变。
+     *
+     * 示例：
+     * ```ts
+     * const result = await sandbox.processTemplate(
+     *   'Notes: ${await copilot.read_file("notes.md", 1, 50)}'
+     * );
+     * ```
+     *
+     * @param text   - 包含 `${...}` 表达式的模板字符串
+     * @param _depth - 内部递归深度计数器（请勿手动传入）
+     */
+    processTemplate(text: string, _depth?: number): Promise<string>;
+    /** @private 解析函数名对应的工具代理路由。 */
+    private _resolveToolProxy;
+    /** @private 通过 AgentRouter 将工具调用代理给远程 agent（绕过 LLM）。 */
+    private _executeViaProxy;
+    /** @private 从远程 agent 获取工具定义（带缓存）。 */
+    private _getRemoteToolDefinitions;
+    /** @private 在远程 agent 模式下执行工具调用。 */
+    private _executeRemote;
+    /** @private 向远程 agent 提交任务（via AgentRouter.submitTask）。 */
+    private _submitRemoteTask;
+    /** @private 将任意工具执行结果规范化为字符串。 */
+    private _normalizeToolResult;
+    /** @private 构建 runCode 的执行上下文（注入 copilot 代理和 context 键）。 */
+    private _createRunCodeContext;
+    /** @private 将代码包装为 AsyncFunction（优先尝试表达式形式，回退语句形式）。 */
+    private _createCodeRunner;
+    /** @private 检查字符串是否为合法 JS 标识符（用于安全注入执行上下文）。 */
+    private _isValidIdentifier;
+    /**
+     * @private 构建 copilot Proxy——将属性访问映射到工具调用。
+     * 内置常用工具（read_file / list_dir 等）的位置参数自动转换为命名参数。
+     */
+    private _buildProxy;
+}
+export default SandboxToolEnv;
+//# sourceMappingURL=SandboxToolEnv.d.ts.map

package/dist-npm/types/src/ai-chat/SandboxToolEnv.d.ts.map

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

package/dist-npm/types/src/audio/AudioEngine.d.ts

@@ -0,0 +1,272 @@
+/**
+ * AudioEngine — browser audio playback & caching with 3-tier storage.
+ *
+ * Cache tiers: Memory (Blob URL + AudioBuffer) → IndexedDB → Network TTS
+ *
+ * 工具函数（常量、IndexedDB、MIDI、超时估算、缓存键）已拆分至 AudioEngine.utils.js。
+ */
+/** 播放回调集合（play / _playAudioBuffer / _playFromUrl / _playMidiSequence 共用） */
+interface AEPlayCallbacks {
+    onEnd?: (() => void) | null;
+    onStart?: (() => void) | null;
+    onError?: ((err?: unknown) => void) | null;
+    generation: number;
+    text?: string;
+    refreshSafetyTimeoutFromMetadata?: boolean;
+}
+export default class AudioEngine {
+    options: Record<string, unknown>;
+    _audioContext: AudioContext | null;
+    _resumePromise: Promise<void> | null;
+    _outputGainNode: GainNode | null;
+    _outputGainContext: AudioContext | null;
+    _outputVolume: number;
+    _blobUrlCache: Map<string, string>;
+    _urlCache: Map<string, {
+        url: string | null;
+        status: string;
+        [key: string]: unknown;
+    }>;
+    _pendingLoads: Map<string, Promise<string | null>>;
+    _audioBufferCache: Map<string, AudioBuffer>;
+    _midiSequenceCache: Map<string, Record<string, unknown>>;
+    _sourceNode: AudioBufferSourceNode | null;
+    _audioElement: HTMLAudioElement | null;
+    _pooledAudio: HTMLAudioElement | null;
+    _urlPlaybackToken: number;
+    _playGeneration: number;
+    _safetyTimeoutId: ReturnType<typeof setTimeout> | null;
+    _midiNodes: Set<unknown>;
+    _midiEndTimerId: ReturnType<typeof setTimeout> | null;
+    _persistentQueue: Array<Record<string, unknown>>;
+    _persistentRunning: boolean;
+    _persistentCancelled: boolean;
+    _persistentTimerId: ReturnType<typeof setTimeout> | null;
+    [key: string]: unknown;
+    constructor(options?: Record<string, unknown>);
+    static getShared(options?: Record<string, unknown>): AudioEngine;
+    configure(options?: Record<string, unknown>): this;
+    setVolume(volume: unknown): this;
+    getVolume(): number;
+    isSupported(): boolean;
+    _getAudioContextCtor(): typeof AudioContext | null;
+    getContext(options?: Record<string, unknown>): AudioContext;
+    getOutputNode(options?: Record<string, unknown>): GainNode;
+    getDestination(options?: Record<string, unknown>): GainNode;
+    resume(options?: Record<string, unknown>): Promise<AudioContext>;
+    /**
+     * Check whether the AudioContext is in a usable (running) state.
+     * Returns false if context hasn't been created or is suspended/closed.
+     */
+    isContextRunning(): boolean;
+    bindUserGesture(target: (EventTarget & {
+        addEventListener?: unknown;
+        removeEventListener?: unknown;
+    }) | null, options?: Record<string, unknown>): () => void;
+    /**
+     * Build a deterministic cache key from text + speech params.
+     */
+    buildCacheKey(text: string, options?: Record<string, unknown>): string;
+    /**
+     * Get a cached Blob URL or CDN URL (synchronous, memory only).
+     * @param {string} text
+     * @param {object} [options] speech params
+     * @returns {string|null}
+     */
+    getCachedUrl(text: string, options?: Record<string, unknown>): string | null;
+    /**
+     * Get a pre-decoded AudioBuffer (synchronous, memory only).
+     */
+    getAudioBuffer(text: string, options?: Record<string, unknown>): AudioBuffer | null;
+    /**
+     * Get a normalized cached MIDI sequence (synchronous, memory only).
+     */
+    getMidiSequence(text: string, options?: Record<string, unknown>): Record<string, unknown> | null;
+    _cacheAudioBlob(cacheKey: string, blob: unknown, options?: Record<string, unknown>): string | null;
+    _cacheAudioUrl(cacheKey: string, url: string, options?: Record<string, unknown>): string | null;
+    _cacheAudioSource(cacheKey: string, source: unknown, options?: Record<string, unknown>): string | null;
+    _cacheMidiSequence(cacheKey: string, sequence: unknown, options?: Record<string, unknown>): Record<string, unknown> | null;
+    /**
+     * Store an externally-obtained audio URL in the cache and
+     * asynchronously download + persist its Blob to IndexedDB.
+     */
+    set(text: string, source: unknown, options?: Record<string, unknown>): unknown;
+    setUrl(text: string, url: string, options?: Record<string, unknown>): unknown;
+    setAudioFile(text: string, file: unknown, options?: Record<string, unknown>): unknown;
+    setAudioData(text: string, data: unknown, options?: Record<string, unknown>): unknown;
+    setMidiSequence(text: string, sequence: unknown, options?: Record<string, unknown>): unknown;
+    /**
+     * Preload a single text → audio entry through three tiers:
+     *   memory Blob URL → IndexedDB → network TTS API
+     *
+     * @param {string} text
+     * @param {object} [options] speech params
+     * @param {function} [options.fetchAudioUrl] async (text, params) => url — custom TTS fetcher
+     * @returns {Promise<string|null>} playable URL
+     */
+    preload(text: string, options?: Record<string, unknown>): Promise<string | null>;
+    /**
+     * Batch-preload multiple items with concurrency control.
+     * @param {Array<string|{text:string, options?:object}>} items
+     * @param {number} [concurrency=3]
+     */
+    preloadBatch(items: Array<string | {
+        text: string;
+        options?: Record<string, unknown>;
+    }>, concurrency?: number): Promise<void>;
+    /**
+     * Background persistent preload queue with automatic retry.
+     */
+    preloadPersistent(items: Array<string | {
+        text: string;
+        options?: Record<string, unknown>;
+    }>, concurrency?: number, retryDelay?: number, batchDelay?: number): Promise<void>;
+    cancelPreload(): void;
+    /**
+     * Warm up memory caches from IndexedDB at app startup.
+     * @returns {Promise<Array<{text:string, options?:object}>>} items not found in IndexedDB
+     */
+    warmupFromDB(items: Array<string | {
+        text: string;
+        options?: Record<string, unknown>;
+    }>): Promise<Array<{
+        text: string;
+        options?: Record<string, unknown>;
+    }>>;
+    /**
+     * Decode a Blob into an AudioBuffer and cache it.
+     * On mobile the AudioContext may be suspended; decodeAudioData still works
+     * in most browsers but we guard against failures gracefully.
+     * @private
+     */
+    _decodeToBuffer(cacheKey: string, blob: Blob): Promise<void>;
+    /**
+     * Play audio for the given text, using the best available cached source.
+     *
+     * Resolution order: pre-decoded AudioBuffer → Blob/CDN URL → skip.
+     *
+     * On mobile, if the AudioContext is suspended (no user gesture), the method
+     * attempts `resume()` but does NOT block indefinitely. Instead it fires
+     * `onEnd` after a reasonable timeout derived from the AudioBuffer duration
+     * or estimated from text length.
+     *
+     * @param {string} text
+     * @param {object} [options]
+     * @param {function} [options.onEnd]
+     * @param {function} [options.onStart]
+     * @param {function} [options.onError]
+     * @param {number}   [options.timeout] explicit safety timeout override (ms)
+     * @returns {{ type: string }|null} playback descriptor or null if nothing to play
+     */
+    play(text: string, options?: Record<string, unknown>): {
+        type: string;
+    } | null;
+    /**
+     * Play an AudioBuffer via Web Audio API.
+     * Attempts resume(); if the context stays suspended after a short wait,
+     * fires onEnd via the safety timeout rather than hanging forever.
+     * @private
+     */
+    _playAudioBuffer(audioBuffer: AudioBuffer, { onEnd, onStart, onError, generation }: AEPlayCallbacks): Promise<void>;
+    /**
+     * Get the shared pooled HTMLAudioElement used by `_playFromUrl`.
+     *
+     * WHY POOLED: On mobile WebViews (especially WeChat X5 / iOS Safari),
+     * each freshly-created `new Audio()` element requires its own user-gesture
+     * unlock. If we kept creating new elements, only the very first one
+     * (played during a user gesture) would be audible — subsequent cache-hit
+     * plays would silently fail while still resolving their promises,
+     * because browsers silently drop autoplay on a never-unlocked element.
+     *
+     * Reusing a single persistent element means only one unlock is required
+     * (via `bindUserGesture()` or the first natural play-during-gesture), and
+     * every later cache-hit play on the same element is permitted.
+     *
+     * The element is attached to `<body>` (hidden) because some mobile
+     * browsers require attachment for `.play()` to dispatch correctly.
+     *
+     * @private
+     */
+    _getPooledAudioElement(): HTMLAudioElement;
+    /**
+     * Play from a URL using a **pooled** HTMLAudioElement.
+     * On iOS/mobile, play() may reject if not called during a user gesture.
+     * In that case we fire onEnd immediately so callers are never left hanging.
+     * @private
+     */
+    _playFromUrl(url: string, { onEnd, onStart, onError, generation, text, refreshSafetyTimeoutFromMetadata }: AEPlayCallbacks): void;
+    /**
+     * Play a cached MIDI-like sequence using simple Web Audio oscillators.
+     * @private
+     */
+    _playMidiSequence(sequence: Record<string, unknown>, { onEnd, onStart, onError, generation }: AEPlayCallbacks): Promise<void>;
+    /**
+     * Stop any audio currently being played through this engine.
+     */
+    stopPlayback(): void;
+    /** @private — generation counter for speak(); independent of _playGeneration */
+    _speakGeneration: number;
+    /** @private — safety timeout for the SDK playKeepworkAudio fallback path */
+    _speakTimeoutId: ReturnType<typeof setTimeout> | null;
+    /** @private */
+    _clearSpeakTimeout(): void;
+    /**
+     * Play TTS audio for `text`, trying cached AudioEngine playback first,
+     * then falling back to the SDK `playKeepworkAudio` path.
+     *
+     * Handles generation-based cancellation so that calling `stopSpeak()` at
+     * any point safely invalidates in-flight async SDK callbacks.
+     *
+     * @param {string} text
+     * @param {object} [options]
+     * @param {function} [options.onEnd]
+     * @param {function} [options.onStart]
+     * @param {function} [options.onError]
+     * @returns {{ type: string }|null}
+     */
+    speak(text: string, options?: Record<string, unknown>): {
+        type: string;
+    } | null;
+    /**
+     * Stop all speech audio: engine playback, SDK-managed audio, and fallback keepwork-audio element.
+     * Also invalidates any in-flight speak() callbacks via generation counter.
+     */
+    stopSpeak(): void;
+    /** @private */
+    _stopCurrentAudio(): void;
+    /** @private */
+    _setSafetyTimeout(safeOnEnd: (() => void) | null | undefined, timeoutMs: number, text: string): void;
+    /** @private */
+    _clearSafetyTimeout(): void;
+    /** @private */
+    _clearMidiEndTimer(): void;
+    /**
+     * Estimate audio playback duration from text length (ms).
+     * Useful for setting timeouts when actual audio duration is unknown.
+     */
+    static estimateDuration(text: string): number;
+    /**
+     * Clear all in-memory caches (does NOT clear IndexedDB).
+     */
+    clearCache(): void;
+    /**
+     * Clear both in-memory caches and IndexedDB persistent cache.
+     */
+    clearAll(): Promise<void>;
+    /**
+     * Get cache statistics (for debugging).
+     */
+    getStats(): {
+        total: number;
+        ready: number;
+        loading: number;
+        error: number;
+        blobCached: number;
+        audioBufferDecoded: number;
+        midiCached: number;
+        persistentQueueSize: number;
+        persistentRunning: boolean;
+    };
+}
+export {};
+//# sourceMappingURL=AudioEngine.d.ts.map

package/dist-npm/types/src/audio/AudioEngine.d.ts.map

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

package/dist-npm/types/src/audio/AudioEngine.utils.d.ts

@@ -0,0 +1,72 @@
+/**
+ * AudioEngine.utils.js — AudioEngine 内部工具层
+ *
+ * 包含：
+ * - 常量（DB 名称、语音参数键、超时配置、音符映射等）
+ * - IndexedDB 辅助函数（_openDB / _getFromDB / _saveToDB / _clearDB）
+ * - Blob/ArrayBuffer 类型检查工具
+ * - MIDI 工具（_midiToFrequency / _noteNameToMidi / _normalizeMidiSequence 等）
+ * - 音频超时估算（_estimateDurationFromText / _timeoutFromBuffer 等）
+ * - 缓存键构建（_buildCacheKey / _extractSpeechParams）
+ *
+ * 供 AudioEngine.js 主类导入使用，不直接暴露给外部。
+ */
+declare const DB_NAME = "keepwork-audio-cache";
+declare const STORE_NAME = "audio-blobs";
+declare const DB_VERSION = 1;
+/** Speech parameter keys that affect audio output (sorted for deterministic serialization) */
+declare const SPEECH_PARAM_KEYS: string[];
+/** Estimated average reading speed: characters per second for CJK text */
+declare const CJK_CHARS_PER_SECOND = 4.5;
+/** Estimated average reading speed: words per second for Latin text */
+declare const LATIN_WORDS_PER_SECOND = 2.5;
+/** Minimum timeout in ms for text-length-based estimates */
+declare const MIN_TEXT_TIMEOUT = 2000;
+/** Maximum timeout in ms for text-length-based estimates */
+declare const MAX_TEXT_TIMEOUT = 60000;
+/** Extra padding added to estimated duration (ms) */
+declare const TIMEOUT_PADDING = 1500;
+/** Minimum timeout for URL/fallback playback when actual duration is unknown */
+declare const MIN_UNKNOWN_AUDIO_TIMEOUT = 5000;
+/** Conservative multiplier for estimated durations when metadata is unavailable */
+declare const UNKNOWN_AUDIO_TIMEOUT_MULTIPLIER = 1.8;
+/** Extra loading budget for SDK TTS fallback before audio playback begins */
+declare const SPEAK_FALLBACK_LOAD_PADDING = 8000;
+/** Maximum timeout for SDK TTS fallback including network loading */
+declare const MAX_SPEAK_FALLBACK_TIMEOUT = 90000;
+declare const AUDIO_RECORD_TYPE = "audioBlob";
+declare const MIDI_RECORD_TYPE = "midiSequence";
+declare const NOTE_NAME_TO_SEMITONE: Record<string, number>;
+declare function _openDB(): Promise<IDBDatabase>;
+declare function _getFromDB(cacheKey: string): Promise<unknown>;
+declare function _saveToDB(cacheKey: string, blob: unknown): Promise<void>;
+declare function _isBlob(value: unknown): value is Blob;
+declare function _isArrayBuffer(value: unknown): value is ArrayBuffer;
+declare function _isArrayBufferView(value: unknown): value is ArrayBufferView;
+declare function _isAudioUrl(value: unknown): boolean;
+declare function _createAudioBlobFromData(data: unknown, mimeType?: string): Blob | null;
+declare function _getAudioSourceFromOptions(options: Record<string, unknown> | null | undefined): unknown;
+declare function _getMidiSequenceFromOptions(options: Record<string, unknown> | null | undefined): unknown;
+declare function _midiToFrequency(note: number): number;
+declare function _noteNameToMidi(noteName: unknown): number | null;
+declare function _normalizeMidiNoteValue(value: unknown): number | null;
+declare function _normalizeMidiSequence(sequence: unknown, options?: Record<string, unknown>): Record<string, unknown> | null;
+declare function _normalizeOutputVolume(value: unknown, fallback?: number): number;
+declare function _clearDB(): Promise<void>;
+declare function _extractSpeechParams(options: Record<string, unknown> | null | undefined): Record<string, unknown> | null;
+declare function _buildCacheKey(text: string, options: Record<string, unknown> | null | undefined): string;
+/**
+ * Estimate audio duration in ms from text content.
+ * Uses CJK character count or Latin word count as heuristic.
+ */
+declare function _estimateDurationFromText(text: string): number;
+/** Derive timeout from an AudioBuffer's actual duration. */
+declare function _timeoutFromBuffer(audioBuffer: AudioBuffer | null | undefined): number | null;
+/** Derive timeout from HTMLMediaElement metadata. */
+declare function _timeoutFromMediaDuration(duration: number): number | null;
+/** Conservative timeout when actual audio duration is not known. */
+declare function _timeoutForUnknownAudio(text: string): number;
+/** Conservative timeout for SDK-managed TTS playback (includes loading budget). */
+declare function _timeoutForSpeakFallback(text: string): number;
+export { DB_NAME, STORE_NAME, DB_VERSION, SPEECH_PARAM_KEYS, CJK_CHARS_PER_SECOND, LATIN_WORDS_PER_SECOND, MIN_TEXT_TIMEOUT, MAX_TEXT_TIMEOUT, TIMEOUT_PADDING, MIN_UNKNOWN_AUDIO_TIMEOUT, UNKNOWN_AUDIO_TIMEOUT_MULTIPLIER, SPEAK_FALLBACK_LOAD_PADDING, MAX_SPEAK_FALLBACK_TIMEOUT, AUDIO_RECORD_TYPE, MIDI_RECORD_TYPE, NOTE_NAME_TO_SEMITONE, _openDB, _getFromDB, _saveToDB, _clearDB, _isBlob, _isArrayBuffer, _isArrayBufferView, _isAudioUrl, _createAudioBlobFromData, _getAudioSourceFromOptions, _getMidiSequenceFromOptions, _midiToFrequency, _noteNameToMidi, _normalizeMidiNoteValue, _normalizeMidiSequence, _normalizeOutputVolume, _extractSpeechParams, _buildCacheKey, _estimateDurationFromText, _timeoutFromBuffer, _timeoutFromMediaDuration, _timeoutForUnknownAudio, _timeoutForSpeakFallback, };
+//# sourceMappingURL=AudioEngine.utils.d.ts.map

package/dist-npm/types/src/audio/AudioEngine.utils.d.ts.map

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