@elizaos/shared 2.0.0-alpha.538 → 2.0.11-beta.7

package/test-support/test-helpers.d.ts

@@ -0,0 +1,79 @@
+import type http from "node:http";
+/** Standardized test result for mocked updater checks. */
+export type MockUpdateCheckResult = {
+    updateAvailable: boolean;
+    currentVersion: string;
+    latestVersion: string | null;
+    channel: string;
+    distTag: string;
+    cached: boolean;
+    error: string | null;
+};
+/** Snapshot and restore the configured environment variables around a test. */
+export declare function createEnvSandbox(keys: readonly string[]): {
+    clear: () => void;
+    restore: () => void;
+};
+export type PluginModuleShape = {
+    [key: string]: unknown;
+    default?: unknown;
+    plugin?: unknown;
+};
+/** Loose plugin-shape predicate used in dynamic test imports across suites. */
+export declare function looksLikePlugin(value: unknown): value is {
+    name: string;
+};
+/** Extract a plugin-like object from a dynamic module export shape. */
+export declare function extractPlugin(mod: PluginModuleShape): {
+    name: string;
+} | null;
+export declare function isPackageImportResolvable(packageName: string): boolean;
+export declare function isWorkspaceDependency(version: string | undefined): boolean;
+export declare function resolveDiscordPluginImportSpecifier(): string | null;
+export declare function resolveTelegramPluginImportSpecifier(): string | null;
+export declare function resolveLensPluginImportSpecifier(): string | null;
+export declare function resolveFarcasterPluginImportSpecifier(): string | null;
+export declare function resolveNostrPluginImportSpecifier(): string | null;
+export declare function resolveMatrixPluginImportSpecifier(): string | null;
+export declare function resolveFeishuPluginImportSpecifier(): string | null;
+export declare function resolveWechatPluginImportSpecifier(): string | null;
+/** Build a mock update check result with deterministic defaults. */
+export declare function buildMockUpdateCheckResult(overrides?: Partial<MockUpdateCheckResult>): MockUpdateCheckResult;
+/** Small utility to wait for asynchronous side-effects in tests. */
+export declare function waitMs(ms: number): Promise<void>;
+type MockResponsePayload<T> = {
+    res: MockHttpServerResponse;
+    getStatus: () => number;
+    getJson: () => T;
+};
+type MockHttpServerResponse = http.ServerResponse & {
+    _status: number;
+    _body: string;
+    writeHead: (statusCode: number) => void;
+};
+type MockBodyChunk = string | Buffer;
+export type MockRequestOptions = {
+    method?: string;
+    url?: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+    bodyChunks?: MockBodyChunk[];
+    json?: boolean;
+};
+/** Create a lightweight mocked HTTP response used by handler tests. */
+export declare function createMockHttpResponse<T = unknown>(): MockResponsePayload<T>;
+export declare function createMockHeadersRequest(headers?: Record<string, string>, options?: Omit<MockRequestOptions, "headers" | "body">): http.IncomingMessage & {
+    destroy: () => void;
+};
+export declare function createMockIncomingMessage({ method, url, headers, body, bodyChunks, json, }: MockRequestOptions): http.IncomingMessage & {
+    destroy: () => void;
+};
+export declare function createMockJsonRequest(body: unknown, options?: Omit<MockRequestOptions, "body" | "json">): http.IncomingMessage & {
+    destroy: () => void;
+};
+/** Return true when optional plugin imports are intentionally unavailable in this env. */
+export declare function isOptionalImportError(error: unknown, extraMarkers?: readonly string[]): boolean;
+/** Safely import optional plugin modules while allowing hard failures to bubble. */
+export declare function tryOptionalDynamicImport<T>(moduleName: string, markers?: readonly string[]): Promise<T | null>;
+export {};
+//# sourceMappingURL=test-helpers.d.ts.map

package/test-support/test-helpers.d.ts.map

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

package/test-support/test-helpers.js

@@ -0,0 +1,341 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { EventEmitter } from "node:events";
+import { existsSync } from "node:fs";
+import { ServerResponse } from "node:http";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+const OPTIONAL_IMPORT_ERROR_MARKERS = [
+    "Cannot find module",
+    "Cannot find package",
+    "ERR_MODULE_NOT_FOUND",
+    "MODULE_NOT_FOUND",
+    "Dynamic require of",
+    "native addon module",
+    "Failed to resolve entry",
+    "tfjs_binding",
+    "NAPI_MODULE_NOT_FOUND",
+    "spec not found",
+];
+/** Snapshot and restore the configured environment variables around a test. */
+export function createEnvSandbox(keys) {
+    const backup = {};
+    function clear() {
+        for (const key of keys) {
+            backup[key] = process.env[key];
+            delete process.env[key];
+        }
+    }
+    function restore() {
+        for (const key of keys) {
+            if (backup[key] === undefined) {
+                delete process.env[key];
+            }
+            else {
+                process.env[key] = backup[key];
+            }
+        }
+    }
+    return { clear, restore };
+}
+/** Loose plugin-shape predicate used in dynamic test imports across suites. */
+export function looksLikePlugin(value) {
+    return (value != null &&
+        typeof value === "object" &&
+        typeof value.name === "string");
+}
+/** Extract a plugin-like object from a dynamic module export shape. */
+export function extractPlugin(mod) {
+    if (looksLikePlugin(mod.default))
+        return mod.default;
+    if (looksLikePlugin(mod.plugin))
+        return mod.plugin;
+    if (looksLikePlugin(mod))
+        return mod;
+    for (const key of Object.keys(mod)) {
+        if (key === "default" || key === "plugin")
+            continue;
+        if (looksLikePlugin(mod[key]))
+            return mod[key];
+    }
+    return null;
+}
+export function isPackageImportResolvable(packageName) {
+    const require = createRequire(import.meta.url);
+    try {
+        require.resolve(packageName);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function isWorkspaceDependency(version) {
+    return (typeof version === "string" &&
+        (version.startsWith(".") || version.startsWith("workspace:")));
+}
+const DISCORD_PLUGIN_PACKAGE_NAME = "@elizaos/plugin-discord";
+const DISCORD_PLUGIN_LOCAL_ENTRY_CANDIDATES = [
+    "../plugins/plugin-discord/dist/index",
+];
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+function resolveFirstExistingPath(relativeEntryPaths) {
+    for (const relativeEntryPath of relativeEntryPaths) {
+        const absoluteEntryPath = path.resolve(PACKAGE_ROOT, relativeEntryPath);
+        if (existsSync(absoluteEntryPath)) {
+            return pathToFileURL(absoluteEntryPath).href;
+        }
+    }
+    return null;
+}
+function resolveNodeModulesEntry(packageName, relativeEntryPath) {
+    const packageSegments = packageName.split("/");
+    const entryPath = path.resolve(PACKAGE_ROOT, "node_modules", ...packageSegments, relativeEntryPath);
+    return existsSync(entryPath) ? pathToFileURL(entryPath).href : null;
+}
+function resolvePluginImportSpecifier({ packageName, alternatePackageNames = [], nodeModulesEntries = [], localEntries = [], }) {
+    for (const candidatePackageName of [packageName, ...alternatePackageNames]) {
+        if (isPackageImportResolvable(candidatePackageName)) {
+            return candidatePackageName;
+        }
+    }
+    for (const entry of nodeModulesEntries) {
+        const resolved = resolveNodeModulesEntry(entry.packageName, entry.relativeEntryPath);
+        if (resolved)
+            return resolved;
+    }
+    return resolveFirstExistingPath(localEntries);
+}
+export function resolveDiscordPluginImportSpecifier() {
+    return resolvePluginImportSpecifier({
+        packageName: DISCORD_PLUGIN_PACKAGE_NAME,
+        localEntries: DISCORD_PLUGIN_LOCAL_ENTRY_CANDIDATES,
+    });
+}
+const TELEGRAM_PLUGIN_PACKAGE_NAME = "@elizaos/plugin-telegram";
+const TELEGRAM_PLUGIN_LOCAL_ENTRY_CANDIDATES = [
+    "../plugins/plugin-telegram/dist/index",
+];
+export function resolveTelegramPluginImportSpecifier() {
+    return resolvePluginImportSpecifier({
+        packageName: TELEGRAM_PLUGIN_PACKAGE_NAME,
+        nodeModulesEntries: [
+            {
+                packageName: TELEGRAM_PLUGIN_PACKAGE_NAME,
+                relativeEntryPath: "dist/index.js",
+            },
+        ],
+        localEntries: TELEGRAM_PLUGIN_LOCAL_ENTRY_CANDIDATES,
+    });
+}
+const LENS_PLUGIN_PACKAGE_NAME = "@elizaos/plugin-lens";
+const LENS_PLUGIN_FALLBACK_PACKAGE = "@elizaos-plugins/client-lens";
+const LENS_PLUGIN_LOCAL_ENTRY_CANDIDATES = [
+    "../plugins/plugin-lens/dist/index",
+    "../../client-lens/dist/index",
+    "../../client-lens/src/index",
+];
+export function resolveLensPluginImportSpecifier() {
+    return resolvePluginImportSpecifier({
+        packageName: LENS_PLUGIN_PACKAGE_NAME,
+        alternatePackageNames: [LENS_PLUGIN_FALLBACK_PACKAGE],
+        nodeModulesEntries: [
+            {
+                packageName: LENS_PLUGIN_FALLBACK_PACKAGE,
+                relativeEntryPath: "src/index.ts",
+            },
+            {
+                packageName: LENS_PLUGIN_FALLBACK_PACKAGE,
+                relativeEntryPath: "dist/index.js",
+            },
+        ],
+        localEntries: LENS_PLUGIN_LOCAL_ENTRY_CANDIDATES,
+    });
+}
+const FARCASTER_PLUGIN_PACKAGE_NAME = "@elizaos/plugin-farcaster";
+const FARCASTER_PLUGIN_LOCAL_ENTRY_CANDIDATES = [
+    "../plugins/plugin-farcaster/dist/node/index.node.js",
+];
+export function resolveFarcasterPluginImportSpecifier() {
+    return resolvePluginImportSpecifier({
+        packageName: FARCASTER_PLUGIN_PACKAGE_NAME,
+        localEntries: FARCASTER_PLUGIN_LOCAL_ENTRY_CANDIDATES,
+    });
+}
+const NOSTR_PLUGIN_PACKAGE_NAME = "@elizaos/plugin-nostr";
+const NOSTR_PLUGIN_LOCAL_ENTRY_CANDIDATES = [
+    "../plugins/plugin-nostr/dist/index",
+];
+export function resolveNostrPluginImportSpecifier() {
+    return resolvePluginImportSpecifier({
+        packageName: NOSTR_PLUGIN_PACKAGE_NAME,
+        localEntries: NOSTR_PLUGIN_LOCAL_ENTRY_CANDIDATES,
+    });
+}
+const MATRIX_PLUGIN_PACKAGE_NAME = "@elizaos/plugin-matrix";
+const MATRIX_PLUGIN_LOCAL_ENTRY_CANDIDATES = [
+    "../plugins/plugin-matrix/dist/index",
+];
+export function resolveMatrixPluginImportSpecifier() {
+    return resolvePluginImportSpecifier({
+        packageName: MATRIX_PLUGIN_PACKAGE_NAME,
+        localEntries: MATRIX_PLUGIN_LOCAL_ENTRY_CANDIDATES,
+    });
+}
+const FEISHU_PLUGIN_PACKAGE_NAME = "@elizaos/plugin-feishu";
+const FEISHU_PLUGIN_LOCAL_ENTRY_CANDIDATES = [
+    "../plugins/plugin-feishu/dist/index",
+];
+export function resolveFeishuPluginImportSpecifier() {
+    return resolvePluginImportSpecifier({
+        packageName: FEISHU_PLUGIN_PACKAGE_NAME,
+        nodeModulesEntries: [
+            {
+                packageName: FEISHU_PLUGIN_PACKAGE_NAME,
+                relativeEntryPath: "dist/index.js",
+            },
+        ],
+        localEntries: FEISHU_PLUGIN_LOCAL_ENTRY_CANDIDATES,
+    });
+}
+const WECHAT_PLUGIN_PACKAGE_NAME = "@elizaos/plugin-wechat";
+const WECHAT_PLUGIN_LEGACY_PACKAGE_NAME = "@elizaai/plugin-wechat";
+const WECHAT_PLUGIN_LOCAL_ENTRY_CANDIDATES = [
+    "src/index.ts",
+    "dist/index.js",
+];
+export function resolveWechatPluginImportSpecifier() {
+    return resolvePluginImportSpecifier({
+        packageName: WECHAT_PLUGIN_PACKAGE_NAME,
+        alternatePackageNames: [WECHAT_PLUGIN_LEGACY_PACKAGE_NAME],
+        nodeModulesEntries: [
+            ...WECHAT_PLUGIN_LOCAL_ENTRY_CANDIDATES.map((relativeEntryPath) => ({
+                packageName: WECHAT_PLUGIN_PACKAGE_NAME,
+                relativeEntryPath,
+            })),
+            ...WECHAT_PLUGIN_LOCAL_ENTRY_CANDIDATES.map((relativeEntryPath) => ({
+                packageName: WECHAT_PLUGIN_LEGACY_PACKAGE_NAME,
+                relativeEntryPath,
+            })),
+        ],
+    });
+}
+/** Build a mock update check result with deterministic defaults. */
+export function buildMockUpdateCheckResult(overrides = {}) {
+    return {
+        updateAvailable: false,
+        currentVersion: "2.0.0",
+        latestVersion: "2.0.0",
+        channel: "stable",
+        distTag: "latest",
+        cached: false,
+        error: null,
+        ...overrides,
+    };
+}
+/** Small utility to wait for asynchronous side-effects in tests. */
+export function waitMs(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** Create a lightweight mocked HTTP response used by handler tests. */
+export function createMockHttpResponse() {
+    let statusCode = 200;
+    let legacyStatus = 0;
+    let payload = "";
+    const res = Object.create(ServerResponse.prototype);
+    Object.defineProperty(res, "statusCode", {
+        get() {
+            return statusCode;
+        },
+        set(value) {
+            statusCode = value;
+            legacyStatus = value;
+        },
+        configurable: true,
+    });
+    res._status = legacyStatus;
+    res._body = payload;
+    res.setHeader = () => res;
+    res.writeHead = ((value) => {
+        statusCode = value;
+        legacyStatus = value;
+        return res;
+    });
+    res.end = ((chunk) => {
+        payload = chunk ? chunk.toString() : "";
+        res._body = payload;
+        legacyStatus = statusCode;
+        res._status = legacyStatus;
+        return res;
+    });
+    return {
+        res,
+        getStatus: () => statusCode,
+        getJson: () => (payload ? JSON.parse(payload) : null),
+    };
+}
+export function createMockHeadersRequest(headers = {}, options = {}) {
+    return createMockIncomingMessage({
+        ...options,
+        headers,
+    });
+}
+export function createMockIncomingMessage({ method = "GET", url = "/", headers = { host: "localhost:2138" }, body, bodyChunks, json = false, }) {
+    const req = new EventEmitter();
+    req.method = method;
+    req.url = url;
+    req.headers = headers;
+    req.destroy = ((_) => req);
+    const chunks = [];
+    if (bodyChunks !== undefined) {
+        for (const chunk of bodyChunks) {
+            chunks.push(typeof chunk === "string" ? Buffer.from(chunk, "utf-8") : chunk);
+        }
+    }
+    else if (body !== undefined) {
+        const encoded = typeof body === "string"
+            ? Buffer.from(body, "utf-8")
+            : body instanceof Buffer
+                ? body
+                : json
+                    ? Buffer.from(JSON.stringify(body), "utf-8")
+                    : Buffer.from(String(body), "utf-8");
+        chunks.push(encoded);
+    }
+    for (const chunk of chunks) {
+        queueMicrotask(() => req.emit("data", chunk));
+    }
+    queueMicrotask(() => req.emit("end"));
+    return req;
+}
+export function createMockJsonRequest(body, options = {}) {
+    return createMockIncomingMessage({
+        ...options,
+        body,
+        json: true,
+    });
+}
+/** Return true when optional plugin imports are intentionally unavailable in this env. */
+export function isOptionalImportError(error, extraMarkers = []) {
+    const message = error instanceof Error ? error.message : String(error);
+    return OPTIONAL_IMPORT_ERROR_MARKERS.concat(extraMarkers).some((marker) => message.includes(marker));
+}
+/** Safely import optional plugin modules while allowing hard failures to bubble. */
+export async function tryOptionalDynamicImport(moduleName, markers) {
+    try {
+        return (await import(__rewriteRelativeImportExtension(/* @vite-ignore */ moduleName)));
+    }
+    catch (error) {
+        if (isOptionalImportError(error, markers))
+            return null;
+        throw error;
+    }
+}
+//# sourceMappingURL=test-helpers.js.map

package/test-support/test-helpers.js.map

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

package/transcripts.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Transcripts — the canonical contract for a recorded + transcribed session.
+ *
+ * One shape, shared across every layer: the ASR/diarization pipeline that
+ * PRODUCES a transcript (plugin-local-inference), the service that STORES it and
+ * mirrors its text into the knowledge/documents store, the API route + client
+ * that TRANSPORT it, and the Transcripts view that PLAYS it back with
+ * word-synced highlighting. Keeping the shape here (pure, browser- + node-safe)
+ * means the word-timing model is defined exactly once.
+ *
+ * Timing convention: every `startMs`/`endMs` is milliseconds from the START of
+ * the recording's audio (0 = first sample), so the same numbers drive both the
+ * stored record and the `<audio>.currentTime`-based player highlight.
+ */
+/** A single transcribed word with playback-synced timing (ms from audio start). */
+export interface TranscriptWord {
+    text: string;
+    startMs: number;
+    endMs: number;
+    /** ASR confidence 0..1, when the backend reports it. */
+    confidence?: number;
+}
+/**
+ * One diarized, word-timed span — a single speaker's contiguous utterance.
+ * `words` is empty only when the ASR backend supplied no per-word timing (the
+ * player then falls back to segment-level highlighting).
+ */
+export interface TranscriptSegment {
+    id: string;
+    /** Stable speaker label within this transcript (e.g. "Speaker 1" or a name). */
+    speakerLabel?: string;
+    /** Resolved elizaOS entity id when the voice was recognized (evidence-linked). */
+    speakerEntityId?: string;
+    startMs: number;
+    endMs: number;
+    /** Segment text (the join of `words`, or raw ASR text when words are absent). */
+    text: string;
+    words: TranscriptWord[];
+    confidence?: number;
+}
+export type TranscriptSource = "voice-session" | "import" | "call" | "unknown";
+/** Visibility scope — mirrors the documents store's `DocumentVisibilityScope`. */
+export type TranscriptScope = "owner-private" | "user-private" | "global" | "agent-private";
+export type TranscriptStatus = "recording" | "processing" | "ready" | "failed";
+/** A recorded + transcribed session: audio + word-timed diarized segments. */
+export interface Transcript {
+    id: string;
+    title: string;
+    /** Epoch ms when recording started. */
+    createdAt: number;
+    /** Epoch ms when the session ended; absent while still recording. */
+    endedAt?: number;
+    durationMs: number;
+    /** Served audio URL (content-addressed media store); absent if not retained. */
+    audioUrl?: string;
+    audioContentType?: string;
+    segments: TranscriptSegment[];
+    source: TranscriptSource;
+    scope: TranscriptScope;
+    status: TranscriptStatus;
+    /** The mirrored documents/knowledge item id (the searchable text copy). */
+    knowledgeDocumentId?: string;
+    /** Distinct speaker count across segments. */
+    speakerCount: number;
+    metadata?: Record<string, unknown>;
+}
+/** Compact list-row projection for the transcripts index. */
+export interface TranscriptSummary {
+    id: string;
+    title: string;
+    createdAt: number;
+    durationMs: number;
+    speakerCount: number;
+    status: TranscriptStatus;
+    /** First slice of the transcript text, for the list row. */
+    preview: string;
+    hasAudio: boolean;
+}
+/** Default characters of transcript text kept for a list-row preview. */
+export declare const TRANSCRIPT_PREVIEW_CHARS = 160;
+/** Distinct speaker labels across the segments (unlabeled segments ignored). */
+export declare function transcriptSpeakerCount(segments: ReadonlyArray<TranscriptSegment>): number;
+/** Recording length in ms — the largest segment end (0 when empty). */
+export declare function transcriptDurationMs(segments: ReadonlyArray<TranscriptSegment>): number;
+/**
+ * Render the transcript as plain, speaker-labeled lines — the exact text that is
+ * mirrored into the knowledge/documents store (so search + the provider read
+ * the same words a human sees) and used for previews. One line per segment:
+ * `Speaker: text` (label omitted when unknown).
+ */
+export declare function transcriptPlainText(segments: ReadonlyArray<TranscriptSegment>): string;
+/** A one-line preview of the transcript text, capped to `max` chars. */
+export declare function transcriptPreview(segments: ReadonlyArray<TranscriptSegment>, max?: number): string;
+/** Project a full transcript to its list-row summary. */
+export declare function summarizeTranscript(transcript: Transcript): TranscriptSummary;
+/** A word flattened across segments, carrying its origin indices for the UI. */
+export interface FlatTranscriptWord extends TranscriptWord {
+    segmentIndex: number;
+    wordIndex: number;
+}
+/** Flatten all segments' words into one time-ordered array (for player sync). */
+export declare function flattenTranscriptWords(segments: ReadonlyArray<TranscriptSegment>): FlatTranscriptWord[];
+/**
+ * Index of the word active at playback time `ms` within a flattened, ascending
+ * word list, via binary search (cheap enough to call every `timeupdate`/frame).
+ * Returns the last word whose `startMs <= ms`; -1 before the first word starts.
+ * A word stays "active" until the next word begins, so gaps between words keep
+ * the previous word lit rather than flickering off.
+ */
+export declare function activeWordIndex(words: ReadonlyArray<FlatTranscriptWord>, ms: number): number;
+//# sourceMappingURL=transcripts.d.ts.map

package/transcripts.d.ts.map

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

package/transcripts.js

@@ -0,0 +1,106 @@
+/**
+ * Transcripts — the canonical contract for a recorded + transcribed session.
+ *
+ * One shape, shared across every layer: the ASR/diarization pipeline that
+ * PRODUCES a transcript (plugin-local-inference), the service that STORES it and
+ * mirrors its text into the knowledge/documents store, the API route + client
+ * that TRANSPORT it, and the Transcripts view that PLAYS it back with
+ * word-synced highlighting. Keeping the shape here (pure, browser- + node-safe)
+ * means the word-timing model is defined exactly once.
+ *
+ * Timing convention: every `startMs`/`endMs` is milliseconds from the START of
+ * the recording's audio (0 = first sample), so the same numbers drive both the
+ * stored record and the `<audio>.currentTime`-based player highlight.
+ */
+/** Default characters of transcript text kept for a list-row preview. */
+export const TRANSCRIPT_PREVIEW_CHARS = 160;
+/** Distinct speaker labels across the segments (unlabeled segments ignored). */
+export function transcriptSpeakerCount(segments) {
+    const labels = new Set();
+    for (const s of segments)
+        if (s.speakerLabel)
+            labels.add(s.speakerLabel);
+    return labels.size;
+}
+/** Recording length in ms — the largest segment end (0 when empty). */
+export function transcriptDurationMs(segments) {
+    let max = 0;
+    for (const s of segments)
+        if (s.endMs > max)
+            max = s.endMs;
+    return max;
+}
+/**
+ * Render the transcript as plain, speaker-labeled lines — the exact text that is
+ * mirrored into the knowledge/documents store (so search + the provider read
+ * the same words a human sees) and used for previews. One line per segment:
+ * `Speaker: text` (label omitted when unknown).
+ */
+export function transcriptPlainText(segments) {
+    return segments
+        .map((s) => {
+        const text = s.text.trim();
+        if (!text)
+            return "";
+        return s.speakerLabel ? `${s.speakerLabel}: ${text}` : text;
+    })
+        .filter((line) => line.length > 0)
+        .join("\n");
+}
+/** A one-line preview of the transcript text, capped to `max` chars. */
+export function transcriptPreview(segments, max = TRANSCRIPT_PREVIEW_CHARS) {
+    const flat = segments
+        .map((s) => s.text.trim())
+        .filter(Boolean)
+        .join(" ")
+        .replace(/\s+/g, " ")
+        .trim();
+    return flat.length > max ? `${flat.slice(0, max - 1).trimEnd()}…` : flat;
+}
+/** Project a full transcript to its list-row summary. */
+export function summarizeTranscript(transcript) {
+    return {
+        id: transcript.id,
+        title: transcript.title,
+        createdAt: transcript.createdAt,
+        durationMs: transcript.durationMs,
+        speakerCount: transcript.speakerCount,
+        status: transcript.status,
+        preview: transcriptPreview(transcript.segments),
+        hasAudio: Boolean(transcript.audioUrl),
+    };
+}
+/** Flatten all segments' words into one time-ordered array (for player sync). */
+export function flattenTranscriptWords(segments) {
+    const out = [];
+    segments.forEach((segment, segmentIndex) => {
+        segment.words.forEach((word, wordIndex) => {
+            out.push({ ...word, segmentIndex, wordIndex });
+        });
+    });
+    return out;
+}
+/**
+ * Index of the word active at playback time `ms` within a flattened, ascending
+ * word list, via binary search (cheap enough to call every `timeupdate`/frame).
+ * Returns the last word whose `startMs <= ms`; -1 before the first word starts.
+ * A word stays "active" until the next word begins, so gaps between words keep
+ * the previous word lit rather than flickering off.
+ */
+export function activeWordIndex(words, ms) {
+    let lo = 0;
+    let hi = words.length - 1;
+    let found = -1;
+    while (lo <= hi) {
+        const mid = (lo + hi) >> 1;
+        if (words[mid].startMs <= ms) {
+            found = mid;
+            lo = mid + 1;
+        }
+        else {
+            hi = mid - 1;
+        }
+    }
+    return found;
+}
+//# sourceMappingURL=transcripts.js.map