@hassangameryt/freeflow 0.7.3 → 0.9.0

package/pi-extension/src/context-virtualization/runtime.ts

@@ -1,428 +0,0 @@
-import {
-  CONTEXT_PROJECTION_ENTRY,
-  CONTEXT_PROJECTION_VERSION,
-  contextRefForEntry,
-  entryIdFromContextRef,
-  type ContextAvailability,
-  type ContextListItem,
-  type ContextOperationResult,
-  type ContextProjection,
-  type ContextProjectionChange,
-  type ContextProjectionJournal,
-  type ContextProjectionResult,
-  type ContextProjectionState,
-  type ContextStatus,
-} from "./types.js";
-import { FreeflowContextRuntime } from "../freeflow-context/runtime.js";
-import type { ContextSourceIdentity, ResolvedContextSource } from "../freeflow-context/types.js";
-import { contentCharacters, projectToolResultMessage, projectedCharacters } from "./projector.js";
-import { replayProjectionEntries } from "./state.js";
-
-function cloneSource(source: ContextSourceIdentity): ContextSourceIdentity {
-  return { ...source };
-}
-
-function sourceProjection(state: ContextProjectionState | undefined): ContextProjection {
-  if (!state || state.mode === "full") return { mode: "full" };
-  return state.retained === undefined ? { mode: "archived" } : { mode: "archived", retained: state.retained };
-}
-
-function safeJsonEqual(left: unknown, right: unknown): boolean {
-  try {
-    return JSON.stringify(left) === JSON.stringify(right);
-  } catch {
-    return false;
-  }
-}
-
-function isDuplicate(values: string[]): string | undefined {
-  const seen = new Set<string>();
-  for (const value of values) {
-    if (seen.has(value)) return value;
-    seen.add(value);
-  }
-  return undefined;
-}
-
-export class ContextVirtualizationRuntime {
-  private readonly pi: any;
-  private readonly freeflowContext: FreeflowContextRuntime;
-  private ctx: any;
-  private sessionId = "current";
-  private branchLeafId: string | null | undefined;
-  private projectionState = new Map<string, ContextProjectionState>();
-  private available = true;
-  private unavailableReason: string | undefined;
-  private mutationQueue: Promise<unknown> = Promise.resolve();
-
-  constructor(pi: any, ctx: any, freeflowContext = new FreeflowContextRuntime(ctx)) {
-    this.pi = pi;
-    this.ctx = ctx;
-    this.freeflowContext = freeflowContext;
-  }
-
-  setContext(ctx: any): void {
-    this.ctx = ctx;
-    this.freeflowContext.setContext(ctx);
-  }
-
-  async recover(ctx = this.ctx, options: { preserveRequest?: boolean } = {}): Promise<boolean> {
-    this.ctx = ctx;
-    this.freeflowContext.setContext(ctx);
-    try {
-      this.sessionId = this.freeflowContext.sessionId();
-      this.branchLeafId = this.freeflowContext.branchLeafId();
-      this.projectionState = replayProjectionEntries(this.freeflowContext.branchEntries(), this.sessionId);
-      if (!options.preserveRequest) this.freeflowContext.clearRequest();
-      this.available = true;
-      this.unavailableReason = undefined;
-      return true;
-    } catch (error) {
-      this.available = false;
-      this.unavailableReason = error instanceof Error ? error.message : String(error);
-      this.freeflowContext.clearRequest();
-      return false;
-    }
-  }
-
-  isAvailable(): boolean {
-    return this.available;
-  }
-
-  isSourceFullyProjected(entryId: string): boolean {
-    if (!this.available) return true;
-    const projection = this.projectionState.get(entryId);
-    return !projection || projection.mode === "full";
-  }
-
-  async project(messages: any[], enabled: boolean): Promise<ContextProjectionResult> {
-    if (!(await this.recover(this.ctx))) {
-      return { messages, changed: false, available: false };
-    }
-
-    const sourcesByToolCallId = this.freeflowContext.resolver.toolResultSources();
-    const refs = new Map<string, ResolvedContextSource>();
-    let changed = false;
-    const projected = messages.map((message) => {
-      if (message?.role !== "toolResult" || typeof message.toolCallId !== "string") return message;
-      const source = sourcesByToolCallId.get(message.toolCallId);
-      if (!source) return message;
-
-      const ref = contextRefForEntry(source.source.entryId);
-      refs.set(ref, source);
-      const state = this.projectionState.get(source.source.entryId);
-      const projection = enabled ? sourceProjection(state) : { mode: "full" as const };
-      const nextMessage = projectToolResultMessage(message, source.source, projection);
-      if (!safeJsonEqual(nextMessage.content, message.content)) changed = true;
-      return nextMessage;
-    });
-
-    const request = enabled ? this.freeflowContext.recordRequest(refs) : undefined;
-    if (!enabled) this.freeflowContext.clearRequest();
-    return {
-      messages: changed ? projected : messages,
-      changed,
-      available: true,
-      generation: request?.generation,
-    };
-  }
-
-  decorate(messages: any[]): any[] {
-    try {
-      const sources = this.freeflowContext.resolver.toolResultSources();
-      return messages.map((message) => {
-        if (message?.role !== "toolResult") return message;
-        const source = sources.get(message.toolCallId);
-        if (!source) return message;
-        const marker = `[context-ref: ${contextRefForEntry(source.source.entryId)}]`;
-        if (
-          (Array.isArray(message.content) ? message.content : []).some(
-            (part: any) =>
-              part.type === "text" &&
-              typeof part.text === "string" &&
-              (part.text === marker ||
-                part.text.startsWith(`[context archived: ${contextRefForEntry(source.source.entryId)}]`)),
-          )
-        )
-          return message;
-        return projectToolResultMessage(message, source.source, { mode: "full" });
-      });
-    } catch {
-      // Decoration must not make Pi fall back to an unprojected context.
-      return messages;
-    }
-  }
-
-  async archive(targets: unknown): Promise<ContextOperationResult> {
-    try {
-      return await this.enqueue(() => this.archiveNow(targets));
-    } catch (error) {
-      return this.rejected("archive", `persistence_failed:${error instanceof Error ? error.message : String(error)}`);
-    }
-  }
-
-  async restore(refs: unknown, actor: "model" | "user" = "model"): Promise<ContextOperationResult> {
-    try {
-      return await this.enqueue(() => this.restoreNow(refs, actor));
-    } catch (error) {
-      return this.rejected("restore", `persistence_failed:${error instanceof Error ? error.message : String(error)}`);
-    }
-  }
-
-  async reset(): Promise<ContextOperationResult> {
-    try {
-      return await this.enqueue(async () => {
-        if (!this.available) return this.unavailable("reset");
-        const journal: ContextProjectionJournal = {
-          version: CONTEXT_PROJECTION_VERSION,
-          actor: "user",
-          reset: "all",
-        };
-        await this.persist(journal);
-        this.projectionState.clear();
-        return {
-          status: "ok",
-          operation: "reset",
-          changed: ["all"],
-          message: "All context projection decisions were reset on the active branch.",
-        };
-      });
-    } catch (error) {
-      return this.rejected("reset", `persistence_failed:${error instanceof Error ? error.message : String(error)}`);
-    }
-  }
-
-  async status(limit = 50): Promise<ContextStatus> {
-    if (!this.available) {
-      return {
-        available: false,
-        unavailableReason: this.unavailableReason,
-        sessionId: this.sessionId,
-        branchLeafId: this.branchLeafId,
-        counts: { full: 0, archived: 0, retained: 0 },
-        originalCharacters: 0,
-        projectedCharacters: 0,
-        historyOnly: 0,
-        unresolved: 0,
-        items: [],
-      };
-    }
-
-    if (!(await this.recover(this.ctx, { preserveRequest: true }))) {
-      return this.status(limit);
-    }
-
-    const branchSources = this.freeflowContext.resolver.sourcesByEntryId();
-    const activeIds = this.freeflowContext.resolver.activeToolResultIds();
-    const items: ContextListItem[] = [];
-
-    for (const source of branchSources.values()) {
-      const state = this.projectionState.get(source.source.entryId);
-      const projection = sourceProjection(state);
-      items.push(this.listItem(source, projection, activeIds.has(source.source.entryId) ? "active" : "history-only"));
-    }
-
-    for (const state of this.projectionState.values()) {
-      if (branchSources.has(state.source.entryId)) continue;
-      const projection = sourceProjection(state);
-      items.push({
-        ref: contextRefForEntry(state.source.entryId),
-        entryId: state.source.entryId,
-        toolCallId: state.source.toolCallId,
-        toolName: state.source.toolName,
-        mode: projection.mode,
-        ...(projection.mode === "archived" && projection.retained !== undefined
-          ? { retained: projection.retained }
-          : {}),
-        originalCharacters: 0,
-        projectedCharacters: projection.mode === "archived" ? contentCharacters(projection.retained ?? "") : 0,
-        availability: "unresolved",
-      });
-    }
-
-    const counts = { full: 0, archived: 0, retained: 0 };
-    let originalCharacters = 0;
-    let projectedCharactersTotal = 0;
-    let historyOnly = 0;
-    let unresolved = 0;
-    for (const item of items) {
-      if (item.mode === "full") counts.full += 1;
-      else {
-        counts.archived += 1;
-        if (item.retained !== undefined) counts.retained += 1;
-      }
-      originalCharacters += item.originalCharacters;
-      projectedCharactersTotal += item.projectedCharacters;
-      if (item.availability === "history-only") historyOnly += 1;
-      if (item.availability === "unresolved") unresolved += 1;
-    }
-
-    return {
-      available: true,
-      sessionId: this.sessionId,
-      branchLeafId: this.branchLeafId,
-      counts,
-      originalCharacters,
-      projectedCharacters: projectedCharactersTotal,
-      historyOnly,
-      unresolved,
-      items: items.slice(-Math.max(1, limit)),
-    };
-  }
-
-  private async archiveNow(targets: unknown): Promise<ContextOperationResult> {
-    if (!this.available) return this.unavailable("archive");
-    if (!Array.isArray(targets) || targets.length === 0) {
-      return this.rejected("archive", "targets_required");
-    }
-    const normalizedRefs = targets.map((target) =>
-      target && typeof target === "object" ? entryIdFromContextRef((target as any).ref) : undefined,
-    );
-    const duplicate = isDuplicate(
-      normalizedRefs.flatMap((ref) => (ref === undefined ? [] : [contextRefForEntry(ref)])),
-    );
-    if (duplicate) return this.rejected("archive", `duplicate_reference:${duplicate}`);
-    const latestRequest = this.freeflowContext.latestRequest();
-    if (!latestRequest) return this.rejected("archive", "no_consumed_context_request");
-
-    const changes: ContextProjectionChange[] = [];
-    const retainedMeaning: Record<string, string> = {};
-    for (let index = 0; index < targets.length; index += 1) {
-      const target = targets[index];
-      if (!target || typeof target !== "object") return this.rejected("archive", `target_${index}_must_be_object`);
-      const ref = normalizedRefs[index];
-      if (!ref) return this.rejected("archive", `target_${index}_invalid_reference`);
-      const normalizedRef = contextRefForEntry(ref);
-      const source = latestRequest.refs.get(normalizedRef);
-      if (!source) return this.rejected("archive", `target_not_in_consumed_context:${normalizedRef}`);
-      const retainedValue = (target as any).retained;
-      if (retainedValue !== undefined && (typeof retainedValue !== "string" || retainedValue.trim() === "")) {
-        return this.rejected("archive", `target_${index}_retained_must_be_non_empty`);
-      }
-      const retained = typeof retainedValue === "string" ? retainedValue.trim() : undefined;
-      changes.push({
-        source: cloneSource(source.source),
-        projection: retained === undefined ? { mode: "archived" } : { mode: "archived", retained },
-      });
-      if (retained !== undefined) retainedMeaning[normalizedRef] = retained;
-    }
-
-    await this.persist({ version: CONTEXT_PROJECTION_VERSION, actor: "model", changes });
-    for (const change of changes) {
-      this.projectionState.set(change.source.entryId, {
-        source: cloneSource(change.source),
-        ...change.projection,
-      });
-    }
-    return {
-      status: "ok",
-      operation: "archive",
-      changed: changes.map((change) => contextRefForEntry(change.source.entryId)),
-      message: `Archived ${changes.length} tool result${changes.length === 1 ? "" : "s"} from future context projections.`,
-      ...(Object.keys(retainedMeaning).length > 0 ? { retained: retainedMeaning } : {}),
-    };
-  }
-
-  private async restoreNow(refs: unknown, actor: "model" | "user"): Promise<ContextOperationResult> {
-    if (!this.available) return this.unavailable("restore");
-    if (!Array.isArray(refs) || refs.length === 0) return this.rejected("restore", "refs_required");
-    const normalizedRefs = refs.map((ref) => entryIdFromContextRef(ref));
-    const duplicate = isDuplicate(
-      normalizedRefs.flatMap((ref) => (ref === undefined ? [] : [contextRefForEntry(ref)])),
-    );
-    if (duplicate) return this.rejected("restore", `duplicate_reference:${duplicate}`);
-
-    const changes: ContextProjectionChange[] = [];
-    const availability: Record<string, ContextAvailability> = {};
-    const activeIds = this.freeflowContext.resolver.activeToolResultIds();
-    const latestRequest = this.freeflowContext.latestRequest();
-    for (let index = 0; index < refs.length; index += 1) {
-      const ref = normalizedRefs[index];
-      if (!ref) return this.rejected("restore", `ref_${index}_invalid_reference`);
-      const normalizedRef = contextRefForEntry(ref);
-      const current = this.projectionState.get(ref);
-      if (!current) return this.rejected("restore", `reference_not_archived:${normalizedRef}`);
-      if (actor === "model" && !latestRequest?.refs.has(normalizedRef)) {
-        return this.rejected("restore", `target_not_in_consumed_context:${normalizedRef}`);
-      }
-      changes.push({ source: cloneSource(current.source), projection: { mode: "full" } });
-      let availabilityValue: ContextAvailability;
-      if (latestRequest?.refs.has(normalizedRef) || activeIds.has(current.source.entryId)) {
-        availabilityValue = "active";
-      } else {
-        availabilityValue = "history-only";
-      }
-      availability[normalizedRef] = availabilityValue;
-    }
-
-    await this.persist({ version: CONTEXT_PROJECTION_VERSION, actor, changes });
-    for (const change of changes) {
-      this.projectionState.set(change.source.entryId, {
-        source: cloneSource(change.source),
-        mode: "full",
-      });
-    }
-    return {
-      status: "ok",
-      operation: "restore",
-      changed: changes.map((change) => contextRefForEntry(change.source.entryId)),
-      availability,
-      message: `Restored ${changes.length} projection${changes.length === 1 ? "" : "s"} to full content.`,
-    };
-  }
-
-  private listItem(
-    source: ResolvedContextSource,
-    projection: ContextProjection,
-    availability: ContextAvailability,
-  ): ContextListItem {
-    const item: ContextListItem = {
-      ref: contextRefForEntry(source.source.entryId),
-      entryId: source.source.entryId,
-      toolCallId: source.source.toolCallId,
-      toolName: source.source.toolName,
-      mode: projection.mode,
-      originalCharacters: contentCharacters(source.message?.content),
-      projectedCharacters: projectedCharacters(source.source, source.message, projection),
-      availability,
-    };
-    if (projection.mode === "archived" && projection.retained !== undefined) {
-      item.retained = projection.retained;
-    }
-    return item;
-  }
-
-  private rejected(operation: ContextOperationResult["operation"], message: string): ContextOperationResult {
-    return { status: "rejected", operation, changed: [], message };
-  }
-
-  private unavailable(operation: ContextOperationResult["operation"]): ContextOperationResult {
-    return {
-      status: "unavailable",
-      operation,
-      changed: [],
-      message: this.unavailableReason ?? "context_virtualization_unavailable",
-    };
-  }
-
-  private persist(journal: ContextProjectionJournal): void | Promise<void> {
-    let append: ((type: string, data: ContextProjectionJournal) => unknown) | undefined;
-    if (typeof this.pi?.appendEntryDurable === "function") {
-      append = this.pi.appendEntryDurable;
-    } else if (typeof this.pi?.appendEntry === "function") {
-      append = this.pi.appendEntry;
-    }
-    if (!append) throw new Error("The Pi host does not expose a session entry persistence method.");
-    const result = append.call(this.pi, CONTEXT_PROJECTION_ENTRY, journal);
-    if (result && typeof result.then === "function") return result;
-  }
-
-  private enqueue<T>(task: () => Promise<T>): Promise<T> {
-    const run = this.mutationQueue.then(task);
-    this.mutationQueue = run.then(
-      () => undefined,
-      () => undefined,
-    );
-    return run;
-  }
-}

package/pi-extension/src/context-virtualization/state.ts

@@ -1,79 +0,0 @@
-import {
-  CONTEXT_PROJECTION_ENTRY,
-  CONTEXT_PROJECTION_VERSION,
-  type ContextProjectionJournal,
-  type ContextProjectionState,
-  isRecord,
-} from "./types.js";
-
-type ProjectionLike = {
-  mode: "full" | "archived";
-  retained?: unknown;
-};
-
-function isProjection(value: unknown): value is ProjectionLike {
-  if (!isRecord(value) || (value.mode !== "full" && value.mode !== "archived")) return false;
-  if (value.mode === "archived" && value.retained !== undefined && typeof value.retained !== "string") return false;
-  return true;
-}
-
-function isJournal(value: unknown): value is ContextProjectionJournal {
-  if (!isRecord(value) || value.version !== CONTEXT_PROJECTION_VERSION) return false;
-  if (value.actor !== "model" && value.actor !== "user") return false;
-  if (value.reset !== undefined && value.reset !== "all") return false;
-  if (value.changes !== undefined && !Array.isArray(value.changes)) return false;
-  return true;
-}
-
-export function replayProjectionEntries(
-  entries: readonly any[],
-  sessionId: string,
-): Map<string, ContextProjectionState> {
-  const state = new Map<string, ContextProjectionState>();
-
-  for (const entry of entries) {
-    if (entry?.type !== "custom" || entry.customType !== CONTEXT_PROJECTION_ENTRY) continue;
-    const data = entry.data;
-    if (!isJournal(data)) continue;
-
-    if (data.reset === "all") {
-      state.clear();
-    }
-
-    for (const change of data.changes ?? []) {
-      if (!isRecord(change) || !isRecord(change.source) || !isProjection(change.projection)) continue;
-      if (change.source.sessionId !== sessionId || typeof change.source.entryId !== "string") continue;
-      if (change.projection.mode === "archived" && change.projection.retained !== undefined) {
-        state.set(change.source.entryId, {
-          source: { ...change.source },
-          mode: "archived",
-          retained: change.projection.retained,
-        });
-      } else if (change.projection.mode === "archived") {
-        state.set(change.source.entryId, {
-          source: { ...change.source },
-          mode: "archived",
-        });
-      } else {
-        state.set(change.source.entryId, {
-          source: { ...change.source },
-          mode: "full",
-        });
-      }
-    }
-  }
-
-  return state;
-}
-
-export function cloneProjectionState(state: Map<string, ContextProjectionState>) {
-  return new Map(
-    [...state.entries()].map(([entryId, projection]) => [
-      entryId,
-      {
-        ...projection,
-        source: { ...projection.source },
-      },
-    ]),
-  );
-}

package/pi-extension/src/context-virtualization/types.ts

@@ -1,92 +0,0 @@
-import type { ContextSourceIdentity } from "../freeflow-context/types.js";
-
-export { CONTEXT_REF_PREFIX, contextRefForEntry, entryIdFromContextRef } from "../freeflow-context/types.js";
-export type {
-  ContextRequestSnapshot,
-  ContextSourceKind,
-  ContextSourceIdentity,
-  ProjectedContextSource,
-  ResolvedContextEntry,
-  ResolvedContextSource,
-  SourceProjectionOutcome,
-} from "../freeflow-context/types.js";
-
-export const CONTEXT_PROJECTION_ENTRY = "freeflow-context-projection";
-export const CONTEXT_PROJECTION_VERSION = 1 as const;
-
-export type ContextProjectionMode = "full" | "archived";
-export type ContextProjectionActor = "model" | "user";
-
-export type ContextProjection = { mode: "full" } | { mode: "archived"; retained?: string };
-
-export type ContextProjectionState = ContextProjection & {
-  source: ContextSourceIdentity;
-};
-
-export type ContextProjectionChange = {
-  source: ContextSourceIdentity;
-  projection: ContextProjection;
-};
-
-export type ContextProjectionJournal = {
-  version: typeof CONTEXT_PROJECTION_VERSION;
-  actor: ContextProjectionActor;
-  changes?: ContextProjectionChange[];
-  reset?: "all";
-};
-
-export type ContextProjectionResult = {
-  messages: any[];
-  changed: boolean;
-  available: boolean;
-  generation?: number;
-};
-
-export type ContextAvailability = "active" | "history-only" | "unresolved";
-
-export type ContextListItem = {
-  ref: string;
-  entryId: string;
-  toolCallId?: string;
-  toolName?: string;
-  mode: ContextProjectionMode;
-  retained?: string;
-  originalCharacters: number;
-  projectedCharacters: number;
-  availability: ContextAvailability;
-};
-
-export type ContextStatus = {
-  available: boolean;
-  unavailableReason?: string;
-  sessionId: string;
-  branchLeafId?: string | null;
-  counts: {
-    full: number;
-    archived: number;
-    retained: number;
-  };
-  originalCharacters: number;
-  projectedCharacters: number;
-  historyOnly: number;
-  unresolved: number;
-  items: ContextListItem[];
-};
-
-export type ContextOperationResult = {
-  status: "ok" | "rejected" | "unavailable";
-  operation: "archive" | "restore" | "reset";
-  changed: string[];
-  message?: string;
-  retained?: Record<string, string>;
-  availability?: Record<string, ContextAvailability>;
-};
-
-export function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-export function projectionCharacters(projection: ContextProjection): number {
-  if (projection.mode === "full") return 0;
-  return projection.retained?.length ?? 0;
-}

package/pi-extension/src/conversation-history/passages.ts

@@ -1,81 +0,0 @@
-export const PASSAGE_TARGET_CHARACTERS = 2_000;
-export const PASSAGE_OVERLAP_CHARACTERS = 200;
-export const SNIPPET_MAX_CHARACTERS = 400;
-
-export type TextPassage = {
-  text: string;
-  start: number;
-  end: number;
-  tokens: string[];
-  length: number;
-};
-
-export function normalizeText(value: string): string {
-  return value.normalize("NFKC").toLocaleLowerCase().replace(/\s+/g, " ").trim();
-}
-
-export function tokenize(value: string): string[] {
-  return normalizeText(value).match(/[\p{L}\p{N}_]+(?:[./:@#$%+-][\p{L}\p{N}_]+)*/gu) ?? [];
-}
-
-export function unique(values: readonly string[]): string[] {
-  return [...new Set(values)];
-}
-
-export function throwIfAborted(signal?: AbortSignal): void {
-  if (!signal?.aborted) return;
-  const error = new Error("conversation_history_search_cancelled");
-  error.name = "AbortError";
-  throw error;
-}
-
-function passageEnd(text: string, start: number): number {
-  const target = Math.min(text.length, start + PASSAGE_TARGET_CHARACTERS);
-  if (target === text.length) return target;
-  const paragraphBreak = text.lastIndexOf("\n\n", target);
-  if (paragraphBreak > start + PASSAGE_TARGET_CHARACTERS / 2) return paragraphBreak + 2;
-  const lineBreak = text.lastIndexOf("\n", target);
-  if (lineBreak > start + PASSAGE_TARGET_CHARACTERS / 2) return lineBreak + 1;
-  return target;
-}
-
-export function splitTextIntoPassages(text: string, signal?: AbortSignal): TextPassage[] {
-  throwIfAborted(signal);
-  if (text.length <= PASSAGE_TARGET_CHARACTERS) {
-    return [{ text, start: 0, end: text.length, tokens: tokenize(text), length: Math.max(1, tokenize(text).length) }];
-  }
-  const result: TextPassage[] = [];
-  let start = 0;
-  while (start < text.length) {
-    throwIfAborted(signal);
-    const end = passageEnd(text, start);
-    const passageText = text.slice(start, end);
-    const tokens = tokenize(passageText);
-    result.push({ text: passageText, start, end, tokens, length: Math.max(1, tokens.length) });
-    if (end >= text.length) break;
-    start = Math.max(start + 1, end - PASSAGE_OVERLAP_CHARACTERS);
-  }
-  return result;
-}
-
-export function snippet(text: string, phrase: string, terms: readonly string[]): string {
-  if (text.length <= SNIPPET_MAX_CHARACTERS) return text;
-  const lower = text.toLocaleLowerCase();
-  const phraseIndex = phrase ? lower.indexOf(phrase) : -1;
-  const termIndex =
-    phraseIndex >= 0
-      ? phraseIndex
-      : terms.reduce((best, term) => {
-          const index = lower.indexOf(term);
-          return index >= 0 && (best < 0 || index < best) ? index : best;
-        }, -1);
-  const center = termIndex >= 0 ? termIndex : 0;
-  let start = Math.max(0, center - Math.floor(SNIPPET_MAX_CHARACTERS / 3));
-  const end = Math.min(text.length, start + SNIPPET_MAX_CHARACTERS);
-  if (end - start < SNIPPET_MAX_CHARACTERS) start = Math.max(0, end - SNIPPET_MAX_CHARACTERS);
-  const prefix = start > 0 ? "…" : "";
-  const suffix = end < text.length ? "…" : "";
-  const available = SNIPPET_MAX_CHARACTERS - prefix.length - suffix.length;
-  const body = text.slice(start, start + available);
-  return `${prefix}${body}${suffix}`;
-}