// The run's focus timeline: which window the scenario was acting on, when.
//
// Focus is DERIVED, never declared — driving a Playwright page focuses the
// browser window; pushing a chat/terminal event focuses the terminal. The
// surfaces call markFocus as a side effect of normal operations, so any
// scenario gets a faithful "where was the developer looking" track for
// free, and scripts/film.ts can cut the session recordings exactly where
// the action moved. Anchors map wall-clock to each recording's own clock.
import { existsSync, readFileSync, writeFileSync } from "node:fs";
import { join } from "node:path";

export type TimelineWindow = "terminal" | "browser";

export interface Timeline {
  /** Wall-clock ms when each recording's clock started. */
  readonly anchors: { terminal?: number; browser?: number };
  /** Focus transitions (first event per contiguous run of a window). */
  readonly focus: Array<{ at: number; window: TimelineWindow }>;
  /** Main-frame navigations — lets the viewer render a live URL bar. */
  readonly nav?: Array<{ at: number; url: string }>;
}

const fileFor = (runDir: string) => join(runDir, "timeline.json");

const read = (runDir: string): Timeline => {
  const file = fileFor(runDir);
  if (!existsSync(file)) return { anchors: {}, focus: [] };
  return JSON.parse(readFileSync(file, "utf8")) as Timeline;
};

const write = (runDir: string, timeline: Timeline) =>
  writeFileSync(fileFor(runDir), JSON.stringify(timeline, null, 1));

/** Record that `window`'s recording clock starts now. */
export const markRecordingStart = (runDir: string, window: TimelineWindow): void => {
  const timeline = read(runDir);
  write(runDir, {
    ...timeline,
    anchors: { ...timeline.anchors, [window]: Date.now() },
  });
};

/** Record that the scenario is acting on `window` (deduped per run). */
export const markFocus = (runDir: string, window: TimelineWindow): void => {
  const timeline = read(runDir);
  if (timeline.focus.at(-1)?.window === window) return;
  timeline.focus.push({ at: Date.now(), window });
  write(runDir, timeline);
};

/** Record a main-frame navigation (deduped against the previous URL). */
export const markNavigation = (runDir: string, url: string): void => {
  const timeline = read(runDir);
  const nav = timeline.nav ?? [];
  if (nav.at(-1)?.url === url) return;
  write(runDir, { ...timeline, nav: [...nav, { at: Date.now(), url }] });
};

export const readTimeline = (runDir: string): Timeline | null =>
  existsSync(fileFor(runDir)) ? read(runDir) : null;

// ---------------------------------------------------------------------------
// Human dwells — pacing for a watchable recording, owned by the framework.
//
// A scenario should never hand-code `waitForTimeout` to make a film readable;
// that's the recording's concern, not the scenario's. A dwell ("beat") is a
// property of a focus transition: when a developer tabs from one tool to
// another, they linger a moment to take in where they landed. So the surfaces
// beat on focus changes (enterFocus) and at the end of a visible step, and the
// splice reads like a person moving between apps.
//
// Beats apply ONLY when filming (E2E_FILM, also implied by the desk's E2E_DESK)
// — fast verification/CI runs, where nobody is watching, pay nothing.
// ---------------------------------------------------------------------------

const FILM_BEAT_MS = 1500;

/** True when this run is producing a recording meant to be watched. */
export const isFilming = (): boolean =>
  process.env.E2E_FILM === "1" || process.env.E2E_DESK === "1";

/** Hold for the viewer — a no-op unless this run is being filmed. */
export const beat = async (ms: number = FILM_BEAT_MS): Promise<void> => {
  if (!isFilming()) return;
  await new Promise((tick) => setTimeout(tick, ms));
};

/**
 * Focus `window`, lingering a beat on the OUTGOING window first when this is a
 * real focus change and we're filming — "look before you tab away". The first
 * focus of a run never beats (nothing to linger on).
 */
export const enterFocus = async (
  runDir: string,
  window: TimelineWindow,
  ms?: number,
): Promise<void> => {
  const previous = read(runDir).focus.at(-1)?.window;
  if (previous !== undefined && previous !== window) await beat(ms);
  markFocus(runDir, window);
};