/**
 * Feature record for one candidate block element. NO DOM dependency: this is
 * the contract between DOM-touching extraction (segment-page.ts) and the
 * pure scorer (classify-block.ts), so the scorer is unit-testable without a
 * browser or jsdom.
 */

export interface BlockGeometry {
  top: number;
  left: number;
  width: number;
  height: number;
  viewportWidth: number;
  viewportHeight: number;
  /** Computed `position`. */
  cssPosition: string;
  overflowX: string;
  zIndex: number;
  isSticky: boolean;
  isAboveFold: boolean;
  isFullWidth: boolean;
  isNarrowColumn: boolean;
  isRowLayout: boolean;
  scrollsHorizontally: boolean;
}

export interface BlockFeatures {
  tagName: string;
  role: string;
  /** `(id + " " + className)`, lowercased, "-"/"_" normalised to spaces. */
  idClass: string;
  ariaLabel: string;
  depth: number;
  /** preorder index / total element count, 0..1 — "near top / near bottom". */
  domOrderRatio: number;

  textLength: number;
  wordCount: number;
  commaCount: number;
  linkTextLength: number;
  linkDensity: number;
  linkCount: number;
  /** Share of links whose text is <= 4 words. */
  shortLinkRatio: number;

  pCount: number;
  headingCount: number;
  /** 7 when no heading is present. */
  minHeadingLevel: number;
  listItemCount: number;
  imageCount: number;
  formControlCount: number;
  buttonCount: number;
  childElementCount: number;
  childBlockCount: number;
  leafCount: number;
  minPosition: number;
  maxPosition: number;

  /** wordCount / max(1, pCount + childBlockCount) — Kohlschütter-style text density. */
  textDensity: number;
  /** textLength / documentTextLength. */
  docTextShare: number;

  /** Filled in by detectCardLists(), 0 otherwise. */
  siblingRepeatCount: number;
  siblingSimilarity: number;

  /** Set only when this element's subtree contains a leaf with name==="calendar". */
  containsCalendarLeaf: boolean;
  /** Set only when this element (or an ancestor already classified) is main. */
  containsDocumentH1: boolean;
  containsLogoImage: boolean;
  containsNavChild: boolean;

  /** undefined in jsdom / when geometry is unavailable — never load-bearing alone. */
  geometry?: BlockGeometry;
}

export interface ScoringContext {
  /** Rank used by SINGLETON_KINDS disambiguation and debug output only. */
  allElementCount: number;
}
