// The phrase console's shapes, constants and its ONE normaliser, with no server
// imports.
//
// This file exists for the reason lib/note-types.ts does, and the break it
// prevents is the same one: PhraseConsole.tsx is a client component and needs
// LEAD_PAD, PAGE_SIZE and normTerms() as VALUES at runtime. A value import is
// not erased, so taking them from lib/phrases.ts would drag node:fs/promises
// into the browser chunk and the build would refuse. `tsc --noEmit` cannot see
// that; only the bundler can.
//
// lib/phrases.ts re-exports everything here, so the server side has one import.

// ---------------------------------------------------------------------------
// The corpus constants. Every one of these is a MEASURED property of the ASR,
// not a preference, so each carries the measurement that set it.
// ---------------------------------------------------------------------------

/**
 * The chunk stride the transcription ran at: parakeet-chunked.mjs uses a 240s
 * chunk with 3s of overlap, so a new chunk starts every 237s.
 *
 * This matters because the merge only drops a word when
 * `|dstart| < 0.12 && x.w === w.w` -- casing and punctuation drift let twins
 * through. There are 3,472 adjacent same-word pairs within 1s in the corpus,
 * and 2,248 of them (65%) sit in a `start % 237 < 3.5` band. That band is an
 * exact discriminator rather than a heuristic: inside it a repeat is an
 * artefact of the seam, outside it the other 1,224 are genuine stutters
 * ("Very, very") and must survive.
 */
export const CHUNK_STEP = 237;
export const CHUNK_OVERLAP = 3.5;

/**
 * Lead-in for a preview, in seconds.
 *
 * Parakeet timestamps a word's START LATE by 25-290ms -- see the note in
 * song/clipwindow.mjs, where the same fact makes the window guards asymmetric.
 * A preview that seeks to `word.start` clips the first phoneme, which reads as
 * the archive being wrong rather than the timestamp.
 *
 * This is a LISTENING pad, not a cut boundary. Nothing here decides where an
 * edit goes; clipWindow() still owns that, and it measures rather than pads.
 */
export const LEAD_PAD = 0.35;
export const TAIL_PAD = 0.35;

/** The in-context audition: enough either side to hear what the line was. */
export const WIDE_PAD = 1.5;

/** Words of context shown each side of a match. */
export const CONTEXT_WORDS = 7;

export const PAGE_SIZE = 50;
export const MAX_PER_PAGE = 200;

/**
 * Terms in one query. `the` alone is 23,081 hits; eight terms is far past any
 * phrase anyone means, and the cap is here so a pathological needle cannot be
 * built by pasting a paragraph in.
 */
export const MAX_TERMS = 8;

// ---------------------------------------------------------------------------
// The shapes.
// ---------------------------------------------------------------------------

export type PhraseOrder = "time" | "conf";

export type PhraseQuery = {
  /** What was typed, verbatim, so the box can be refilled with it. */
  q: string;
  /** What is actually searched for. normTerms(q). */
  terms: string[];
  /** One episode, or the whole corpus. */
  video: string | null;
  /** Minimum confidence, or null for no filter -- which is the DEFAULT. */
  minConf: number | null;
  /** Drop hits from episodes flagged in suspect-sources.json. */
  clean: boolean;
  /**
   * Fold chunk twins. `dupes=1` (the default) folds them and reports the count
   * as `collapsed`; `dupes=0` shows every raw match.
   *
   * Read the flag as "the dupe-folding is on", not as "dupes are shown" -- it
   * is the folding that is being switched, and `total` goes DOWN when it is 1.
   */
  dupes: boolean;
  order: PhraseOrder;
  /** 1-based. */
  page: number;
  per: number;
};

export type PhraseHit = {
  /**
   * `<video>#<wordIndex>`. NEVER a timestamp: about one pair per 100k words
   * shares a `start`, so a time-keyed id would collide and a starred pick would
   * silently address the wrong word.
   */
  id: string;
  video: string;
  /** Falls back to the bare id: titles.json covers 298 of 300 episodes. */
  title: string;
  date: string;
  /** Word index of the first matched word, and how many words the match spans. */
  i: number;
  n: number;
  start: number;
  end: number;
  /** The matched words AS WRITTEN, never normalised. */
  text: string;
  before: string;
  after: string;
  /** null means UNKNOWN, never 1.0. The type dropped conf; the data has it. */
  confMin: number | null;
  confMean: number | null;
  /** The preview window, lead-in already applied. */
  from: number;
  to: number;
  /** This EPISODE is in suspect-sources.json. Per-episode, never per-moment. */
  suspect: boolean;
  /** Chunk twins folded into this hit. */
  dupes: number;
  /** A real repeat: within 0.6s of its predecessor and outside any seam band. */
  stutter: boolean;
  hasVideo: boolean;
  archive: string | null;
};

export type PhraseResult = {
  query: PhraseQuery;
  /** The page slice only. */
  hits: PhraseHit[];
  /** Every match under these filters, uncapped. */
  total: number;
  /** Twins folded. Stated, never silent. */
  collapsed: number;
  /** Matches removed by the confidence and flagged-source filters. */
  suppressed: number;
  videos: number;
  ms: number;
  corpus: { videos: number; words: number; builtAt: number | null; heapMb: number };
  notes: string[];
};

// ---------------------------------------------------------------------------
// The normaliser. ONE function, applied identically to the query and to the
// corpus -- if they ever diverge, a word becomes unfindable and nothing says so.
// ---------------------------------------------------------------------------

const CURLY = /[\u2018\u2019\u02bc\u201b]/g;
const MARKS = /[\u0300-\u036f]/g;
const NON_ASCII = /[^\x00-\x7f]/;

/**
 * Split a string into search terms.
 *
 * TERMS, PLURAL, and that is the whole point. 18 tokens in the corpus contain
 * an internal space -- `just 'cause`, `buy 'em`, `L.A.` -- so any
 * one-token-one-term normaliser makes them permanently unfindable, silently.
 * Here `L.A.` becomes `["l","a"]` on both sides of the comparison, so typing
 * either "L.A." or "l a" finds it.
 *
 * Zero tokens in the corpus are hyphenated (`uh-huh` and `mm-hmm` are human
 * labels from lib/vocab.ts, never ASR output), so a hyphen is a query-side term
 * separator and nothing more.
 */
export function normTerms(s: string): string[] {
  let t = s.toLowerCase().replace(CURLY, "'");
  // Fold diacritics so "café" and "cafe" are the same term. Guarded because it
  // runs 623,079 times on a cold build and almost never has anything to do.
  if (NON_ASCII.test(t)) t = t.normalize("NFD").replace(MARKS, "");
  const out: string[] = [];
  for (const part of t.split(/[^a-z0-9']+/)) {
    const term = part.replace(/^'+/, "").replace(/'+$/, "");
    if (term) out.push(term);
  }
  return out;
}

/** A hit's identity. The word index, never the time. */
export const hitId = (video: string, i: number): string => `${video}#${i}`;

/** Is this second inside a chunk seam, where a same-word repeat is an artefact? */
export const inChunkOverlap = (start: number): boolean =>
  start % CHUNK_STEP < CHUNK_OVERLAP;

/**
 * The window to preview. `from` is always at least LEAD_PAD before the word, so
 * the late timestamp cannot clip the onset, and it is clamped at 0 -- a hit at
 * 0.28s would otherwise ask for -0.07.
 */
export function previewWindow(
  hit: { start: number; end: number },
  wide = false,
): { from: number; to: number } {
  const lead = wide ? WIDE_PAD : LEAD_PAD;
  const tail = wide ? WIDE_PAD : TAIL_PAD;
  return {
    from: +Math.max(0, hit.start - lead).toFixed(3),
    to: +(hit.end + tail).toFixed(3),
  };
}

// ---------------------------------------------------------------------------
// Trap 1, and it has to be said out loud.
//
// The ASR barely transcribes fillers: `um` is 2 occurrences in 623,079 tokens,
// `uh` is 5, `huh` 9, `hmm` 2, `erm` 1. That is exactly WHY the um palette was
// mined acoustically into cand2/ rather than read out of the transcript.
//
// The first thing anyone types into this box will be "um", and it will return
// two rows. Without a note saying so, the console reads as broken on contact.
// ---------------------------------------------------------------------------

const FILLERS = new Set([
  "um", "umm", "uh", "uhh", "er", "erm", "hmm", "hm", "mm", "mmm", "huh", "ah", "eh",
]);

export const isFillerQuery = (terms: string[]): boolean =>
  terms.length > 0 && terms.every((t) => FILLERS.has(t));

// ---------------------------------------------------------------------------
// One parser, so the page and the API can never disagree about what a URL
// means. Errors are RETURNED rather than thrown: the page renders them as notes
// and still draws the box, the API turns them into a 400.
// ---------------------------------------------------------------------------

export type PhraseQueryError = { field: string; message: string };

const num = (v: string | null): number | null => {
  if (v == null || v === "") return null;
  const n = Number(v);
  return Number.isFinite(n) ? n : null;
};

export function parsePhraseQuery(sp: URLSearchParams): {
  query: PhraseQuery;
  errors: PhraseQueryError[];
} {
  const errors: PhraseQueryError[] = [];
  const q = (sp.get("q") ?? "").slice(0, 400);
  let terms = normTerms(q);

  if (q.trim() && terms.length === 0) {
    errors.push({ field: "q", message: "nothing searchable in that -- punctuation only" });
  }
  if (terms.length > MAX_TERMS) {
    errors.push({ field: "q", message: `at most ${MAX_TERMS} terms; that is ${terms.length}` });
    terms = terms.slice(0, MAX_TERMS);
  }

  const rawPer = num(sp.get("per"));
  if (rawPer != null && rawPer > MAX_PER_PAGE) {
    errors.push({ field: "per", message: `per is capped at ${MAX_PER_PAGE}` });
  }
  const per = Math.max(1, Math.min(MAX_PER_PAGE, Math.round(rawPer ?? PAGE_SIZE)));

  const minConf = num(sp.get("conf"));
  const order = sp.get("order") === "conf" ? "conf" : "time";

  return {
    query: {
      q,
      terms,
      video: sp.get("video") || null,
      // No DEFAULT confidence floor. Only 1.1% of tokens fall below 0.4, and for
      // a word edit a low-confidence token is often the interesting one -- the
      // machine heard something it could not place. Show conf, offer the filter.
      minConf: minConf != null && minConf > 0 ? minConf : null,
      clean: sp.get("clean") === "1",
      dupes: sp.get("dupes") !== "0",
      order,
      page: Math.max(1, Math.round(num(sp.get("page")) ?? 1)),
      per,
    },
    errors,
  };
}