/**
 * Wire / in-memory types for the Reading Mode v2 structural analysis layer.
 * This file has NO DOM dependency so it can be imported unchanged by both
 * the source-side analyzer and the reader-side renderer (and by pure tests).
 */

export type BlockKind =
  | "root"
  | "header"
  | "nav"
  | "breadcrumb"
  | "search"
  | "toolbar"
  | "pagination"
  | "main"
  | "article"
  | "section"
  | "aside"
  | "footer"
  | "cardList"
  | "card"
  | "list"
  | "gallery"
  | "table"
  | "form"
  | "calendar"
  | "embed"
  | "consent"
  | "promo"
  | "contentGroup";

/**
 * Kinds whose internals are owned by an existing leaf producer
 * (explore-table/form/calendar-helper, or the milestone-2 card/gallery
 * renderer) and must therefore never be descended into by the segmenter.
 */
export const TERMINAL_KINDS: ReadonlySet<BlockKind> = new Set([
  "table",
  "form",
  "calendar",
  "embed",
  "card",
  "gallery",
  "breadcrumb",
  "pagination",
  "toolbar",
  "search",
]);

/** Leaves under these kinds are dropped from the reader output entirely. */
export const DROPPED_KINDS: ReadonlySet<BlockKind> = new Set([
  "consent",
  "promo",
]);

/**
 * Rendered WITHOUT a wrapper: children/leaves are spliced straight into the
 * parent. This is the escape hatch that makes a page the classifier can't
 * read degrade to exactly today's flat rendering, for free.
 */
export const TRANSPARENT_KINDS: ReadonlySet<BlockKind> = new Set([
  "contentGroup",
  "root",
]);

/** Kinds that are unique per document; losers are demoted to `section`. */
export const SINGLETON_KINDS: ReadonlySet<BlockKind> = new Set([
  "header",
  "footer",
  "main",
]);

export interface CardSlots {
  title?: number;
  image?: number;
  summary?: number;
  link?: number;
  meta?: number[];
}

/**
 * Wire format: FLAT array, preorder, parents always precede their children.
 * Rebuilt into a tree reader-side in one linear pass (see block-tree.ts).
 */
export interface SerializedBlock {
  /** Stable id within one INIT_HTML payload. */
  i: number;
  /** Parent id, or null for direct children of the synthetic root. */
  p: number | null;
  k: BlockKind;
  /** Confidence, 0..1, 2 decimal places. */
  c: number;
  /** Leaf `ReaderObject.position`s owned DIRECTLY by this block, ascending. */
  l: number[];
  /**
   * Subtree position range [min, max], inclusive. BUILD TIME ONLY — becomes
   * stale as soon as `data-position` is renumbered by the incremental sync
   * handlers, so the renderer must never consult it after the initial paint.
   */
  r: [number, number];
  /** Label: heading text / aria-label / synthesized. */
  n?: string;
  /** Heading level found for this block's own leaves, if any. */
  h?: number;
  /** Structural fingerprint, cardList only. */
  f?: string;
  /** Card content slots, card only. */
  s?: CardSlots;
  /**
   * Gallery only: per-slide leaf position groups (the slide's image plus
   * any short caption travelling with it), in slide order.
   */
  gs?: number[][];
  /** Gallery only: index into `gs` of the slide that was visible on the source page. */
  ga?: number;
  /** Top-3 scores, debug builds only. */
  d?: Record<string, number>;
}

export interface SerializedBlockTree {
  version: 1;
  blocks: SerializedBlock[];
  /** Leaf positions the reader must ignore entirely (consent/promo). */
  dropped: number[];
  stats: {
    blocks: number;
    dropped: number;
    ms: number;
    bailed?: string;
  };
}
