SheetCompressor.osts

// GENERATED by packages/officescript/scripts/generate-bundle.ts — DO NOT EDIT BY HAND.
// Source of truth: packages/typescript/src/ (the verified reference core).
// Regenerate with: npm run generate (in packages/officescript).

// Minimal ExcelScript host types. In Excel Online these are provided by the
// runtime; we declare just the surface main()/chart extraction touches so the
// generated .osts type-checks locally with NO node libs.
declare namespace ExcelScript {
  interface Range {
    getTexts(): string[][];
    getRowIndex(): number;
    getColumnIndex(): number;
    getAddressLocal?(): string;
  }
  interface ChartTitle {
    getText(): string;
  }
  interface Chart {
    getName(): string;
    getChartType(): ChartType;
    getTitle(): ChartTitle;
    getImage(): string;
  }
  interface Worksheet {
    getUsedRange(): Range | undefined;
    getCharts(): Chart[];
    getName(): string;
  }
  interface Workbook {
    getWorksheet(name: string): Worksheet | undefined;
    getActiveWorksheet(): Worksheet;
  }
  // The runtime ChartType enum is large; we only need it as an opaque string
  // tag for the type mapping in main(). Declaring it as a string keeps the
  // local typecheck free of the full enum while matching the runtime values
  // (the enum members serialize to these lowercase-ish identifiers).
  type ChartType = string;
}

namespace SheetCompressorInternal {
  // --- types.ts ---
  // Public types for the sheet-compressor TypeScript reference implementation.
  // See ../../../spec/SPEC.md for the language-neutral contract.

  export type Origin = {
    /** 1-indexed row of the grid's top-left cell. */
    row: number;
    /** 1-indexed column of the grid's top-left cell. */
    col: number;
  };

  export type DataType =
    | "text"
    | "number"
    | "date"
    | "bool"
    | "formula"
    | "error"
    | "empty";

  export type CellMeta = {
    dataType?: DataType;
  };

  export type ChartType = "bar" | "line" | "pie" | "scatter" | "area" | "other";

  export type ChartDescriptor = {
    name: string;
    type: ChartType;
    anchorRange: string;
    title?: string;
    dataRanges?: string[];
    series?: string[];
    axes?: { x?: string; y?: string };
  };

  export type Grid = {
    rows: string[][];
    origin: Origin;
    cellMeta?: CellMeta[][];
    charts?: ChartDescriptor[];
  };

  /**
   * The result of anchor detection: which rows and columns (0-indexed into
   * `grid.rows`) the active strategy decided to keep. The anchor encoder emits
   * cells only at `(r, c)` where `r ∈ keptRows` AND `c ∈ keptCols`.
   */
  export type AnchorDetection = {
    keptRows: ReadonlySet<number>;
    keptCols: ReadonlySet<number>;
  };

  /**
   * Pluggable anchor-detection strategy. See SPEC §3.1 for the contract.
   * v0 ships `keep-all` (legacy no-op) and `phase1` (the default).
   */
  export type AnchorStrategy = {
    readonly name: string;
    detect(grid: Grid): AnchorDetection;
  };

  /** Built-in strategy selectors. */
  export type AnchorStrategyName = "keep-all" | "phase1";

  /**
   * Pure function string → token count. Injected via {@link CompressOptions} so
   * callers can supply a real tokenizer (gpt-tokenizer / js-tiktoken / …) without
   * coupling the core to one. Must be deterministic for a given input.
   */
  export type TokenCounter = (s: string) => number;

  export type CompressOptions = {
    /**
     * Anchor-detection strategy. Pass a built-in name or a custom
     * `AnchorStrategy`. Defaults to `"phase1"`.
     */
    anchorStrategy?: AnchorStrategyName | AnchorStrategy;
    /**
     * Counts tokens for the raw-baseline and each encoding's `string`. Defaults
     * to the shared SPEC heuristic (see `estimateTokens`) when omitted, which is
     * the only counter every cross-language port is required to agree on.
     */
    tokenCounter?: TokenCounter;
  };

  export type AnchorJson = {
    encoding: "anchor-skeleton";
    version: 0;
    origin: Origin;
    cells: Array<{ address: string; value: string }>;
  };

  export type InvertedIndexJson = {
    encoding: "inverted-index";
    version: 0;
    origin: Origin;
    groups: Array<{ value: string; ranges: string[] }>;
  };

  export type FormatType =
    | "IntNum"
    | "FloatNum"
    | "ScientificNum"
    | "PercentageNum"
    | "CurrencyData"
    | "DateData"
    | "TimeData"
    | "YearData"
    | "EmailData"
    | "Boolean"
    | "Text";

  export type FormatAggregationJson = {
    encoding: "format-aggregation";
    version: 0;
    origin: Origin;
    groups: Array<{ type: FormatType; ranges: string[] }>;
  };

  export type Encoding<TJson = unknown> = {
    string: string;
    json: TJson;
    tokenEstimate: number;
  };

  export type CompressResult = {
    encodings: {
      anchor: Encoding<AnchorJson>;
      invertedIndex: Encoding<InvertedIndexJson>;
      formatAggregation: Encoding<FormatAggregationJson>;
    };
    /**
     * Echo of `grid.charts` in input order, after CHART(...) tokens have already
     * been appended into each encoding's `.string` (SPEC §6). Empty array when
     * `grid.charts` is missing or empty.
     */
    charts: ChartDescriptor[];
    rawBaseline: { tokenEstimate: number };
  };

  // --- address.ts ---
  /**
   * 1-indexed column number → Excel column letters.
   *   1 → "A", 26 → "Z", 27 → "AA", 52 → "AZ", 702 → "ZZ", 703 → "AAA".
   */
  export function colToLetters(col: number): string {
    if (!Number.isInteger(col) || col < 1) {
      throw new RangeError(`column must be a positive integer, got ${col}`);
    }
    let n = col;
    let out = "";
    while (n > 0) {
      const rem = (n - 1) % 26;
      out = String.fromCharCode(65 + rem) + out;
      n = Math.floor((n - 1) / 26);
    }
    return out;
  }

  /** Format an A1 address from 1-indexed (row, col). */
  export function a1(row: number, col: number): string {
    return `${colToLetters(col)}${row}`;
  }

  // --- encodings/escape.ts ---
  /**
   * Per SPEC §3.2 rules 1–6: backslash first (so later rules' backslashes aren't
   * double-escaped), then the delimiters, then the whitespace controls. Shared by
   * the anchor and inverted-index encodings (SPEC §4.4 reuses these rules).
   */
  export function escapeValue(v: string): string {
    return v
      .replace(/\\/g, "\\\\")
      .replace(/,/g, "\\,")
      .replace(/\|/g, "\\|")
      .replace(/\n/g, "\\n")
      .replace(/\r/g, "\\r")
      .replace(/\t/g, "\\t");
  }

  // --- baseline.ts ---
  /**
   * The "vanilla" un-compressed representation of a grid: rows joined with ` | `,
   * separated by `\n`, no escaping, no address prefixes. This is the form
   * `rawBaseline.tokenEstimate` is measured against — i.e. the raw text a
   * developer would otherwise paste into a prompt.
   */
  export function vanillaEncode(grid: Grid): string {
    return grid.rows.map((row) => row.join(" | ")).join("\n");
  }

  // --- tokens.ts ---
  /**
   * v0 heuristic token counter (SPEC §7): `ceil(utf16-code-units / 4)`, with
   * `""` → 0. Deterministic, dependency-free, and the shared cross-language
   * baseline every implementation MUST agree on. Real tokenizers are layered on
   * top via {@link createTokenCounter} or any user-supplied
   * {@link TokenCounter}.
   */
  export function estimateTokens(s: string): number {
    if (s.length === 0) return 0;
    return Math.ceil(s.length / 4);
  }

  // --- encodings/chartDescriptors.ts ---
  /**
   * Per SPEC §6.1: the contents of a double-quoted token field (title, xAxis,
   * yAxis). Backslash first so later rules' backslashes aren't double-escaped,
   * then the quote, then the whitespace controls.
   */
  function escapeQuoted(s: string): string {
    return s
      .replace(/\\/g, "\\\\")
      .replace(/"/g, '\\"')
      .replace(/\n/g, "\\n")
      .replace(/\r/g, "\\r")
      .replace(/\t/g, "\\t");
  }

  /**
   * Per SPEC §6.1: a single series name inside `series=[…]`. Backslash first,
   * then the bracket-list delimiters (`,` and `]`), then the whitespace controls.
   */
  function escapeSeriesName(s: string): string {
    return s
      .replace(/\\/g, "\\\\")
      .replace(/,/g, "\\,")
      .replace(/\]/g, "\\]")
      .replace(/\n/g, "\\n")
      .replace(/\r/g, "\\r")
      .replace(/\t/g, "\\t");
  }

  /**
   * Render a single chart descriptor to the SPEC §6.1 token form. Optional
   * fields are omitted entirely when undefined or (for `dataRanges`/`series`)
   * when the source array is empty. The `name` field is intentionally not
   * rendered — it is a developer-facing identifier, not LLM context.
   */
  export function renderChartToken(chart: ChartDescriptor): string {
    const parts: string[] = [`CHART(${chart.type})@${chart.anchorRange}`];
    if (chart.title !== undefined) {
      parts.push(`title="${escapeQuoted(chart.title)}"`);
    }
    if (chart.dataRanges && chart.dataRanges.length > 0) {
      parts.push(`data=${chart.dataRanges.join(",")}`);
    }
    if (chart.series && chart.series.length > 0) {
      parts.push(`series=[${chart.series.map((s) => escapeSeriesName(s)).join(",")}]`);
    }
    if (chart.axes?.x !== undefined) {
      parts.push(`xAxis="${escapeQuoted(chart.axes.x)}"`);
    }
    if (chart.axes?.y !== undefined) {
      parts.push(`yAxis="${escapeQuoted(chart.axes.y)}"`);
    }
    return parts.join(" ");
  }

  /**
   * Per SPEC §6.2: tokens joined by `\n` in input order, no trailing newline.
   * Returns `""` when `charts` is missing or empty.
   */
  export function renderChartBlock(
    charts: ChartDescriptor[] | undefined,
  ): string {
    if (!charts || charts.length === 0) return "";
    return charts.map((c) => renderChartToken(c)).join("\n");
  }

  /**
   * Per SPEC §6.2: append the chart block to a cell-string with the documented
   * separator rule. Empty inputs collapse cleanly: empty cells + charts → charts
   * only; cells + no charts → cells only; both empty → empty string.
   */
  export function appendChartBlock(cellString: string, chartBlock: string): string {
    if (chartBlock === "") return cellString;
    if (cellString === "") return chartBlock;
    return `${cellString}\n${chartBlock}`;
  }

  // --- encodings/anchor.ts ---
  export function encodeAnchor(
    grid: Grid,
    detection: AnchorDetection,
    tokenCounter: TokenCounter,
  ): Encoding<AnchorJson> {
    const cells: AnchorJson["cells"] = [];
    const lines: string[] = [];

    for (let r = 0; r < grid.rows.length; r++) {
      if (!detection.keptRows.has(r)) continue;
      const row = grid.rows[r] ?? [];
      const tokens: string[] = [];
      for (let c = 0; c < row.length; c++) {
        if (!detection.keptCols.has(c)) continue;
        const value = row[c] ?? "";
        // SPEC §3.1: only literal "" is empty.
        if (value === "") continue;
        const address = a1(grid.origin.row + r, grid.origin.col + c);
        cells.push({ address, value });
        tokens.push(`${address},${escapeValue(value)}`);
      }
      // SPEC §3.2: fully-empty rows are dropped (no blank line emitted).
      if (tokens.length > 0) lines.push(tokens.join("|"));
    }

    const string = lines.join("\n");
    const json: AnchorJson = {
      encoding: "anchor-skeleton",
      version: 0,
      origin: { row: grid.origin.row, col: grid.origin.col },
      cells,
    };
    return { string, json, tokenEstimate: tokenCounter(string) };
  }

  // --- encodings/invertedIndex.ts ---
  /** Pack absolute (row, col) into a single number for Map/Set keys. */
  function pack(row: number, col: number): number {
    return row * 0x100000 + col;
  }

  /**
   * Inverted-index encoding per SPEC §4: group cells by value, then collapse
   * each group's cells into the minimal list of A1 rectangles via a deterministic
   * width-first greedy scan over row-major order.
   */
  export function encodeInvertedIndex(
    grid: Grid,
    tokenCounter: TokenCounter,
  ): Encoding<InvertedIndexJson> {
    // Walk the grid in row-major order, bucketing every non-empty cell by value.
    // Map preserves insertion order, so iterating cellsByValue later yields
    // values ordered by first cell address — exactly the order SPEC §4.4 wants.
    const cellsByValue = new Map<string, number[]>();

    for (let r = 0; r < grid.rows.length; r++) {
      const row = grid.rows[r] ?? [];
      for (let c = 0; c < row.length; c++) {
        const value = row[c] ?? "";
        if (value === "") continue;
        const key = pack(grid.origin.row + r, grid.origin.col + c);
        const bucket = cellsByValue.get(value);
        if (bucket === undefined) {
          cellsByValue.set(value, [key]);
        } else {
          bucket.push(key);
        }
      }
    }

    const groups: InvertedIndexJson["groups"] = [];
    for (const [value, cellKeys] of Array.from(cellsByValue)) {
      const present = new Set(cellKeys);
      const assigned = new Set<number>();
      const ranges: string[] = [];

      for (const startKey of cellKeys) {
        if (assigned.has(startKey)) continue;
        const startRow = Math.floor(startKey / 0x100000);
        const startCol = startKey % 0x100000;

        // Maximum width: extend right while cells are in the value-set AND
        // not already absorbed by an earlier rectangle from a row above.
        let width = 1;
        while (
          present.has(pack(startRow, startCol + width)) &&
          !assigned.has(pack(startRow, startCol + width))
        ) {
          width++;
        }

        // Maximum height: extend down while every cell in the row of `width`
        // cells is still in the value-set and unassigned.
        let height = 1;
        while (true) {
          const nextRow = startRow + height;
          let canExtend = true;
          for (let dc = 0; dc < width; dc++) {
            const k = pack(nextRow, startCol + dc);
            if (!present.has(k) || assigned.has(k)) {
              canExtend = false;
              break;
            }
          }
          if (!canExtend) break;
          height++;
        }

        for (let dr = 0; dr < height; dr++) {
          for (let dc = 0; dc < width; dc++) {
            assigned.add(pack(startRow + dr, startCol + dc));
          }
        }

        const topLeft = a1(startRow, startCol);
        if (width === 1 && height === 1) {
          ranges.push(topLeft);
        } else {
          ranges.push(
            `${topLeft}:${a1(startRow + height - 1, startCol + width - 1)}`,
          );
        }
      }

      groups.push({ value, ranges });
    }

    const string = groups
      .map((g) => `${g.ranges.join("|")},${escapeValue(g.value)}`)
      .join("\n");

    const json: InvertedIndexJson = {
      encoding: "inverted-index",
      version: 0,
      origin: { row: grid.origin.row, col: grid.origin.col },
      groups,
    };
    return { string, json, tokenEstimate: tokenCounter(string) };
  }

  // --- encodings/formatAggregation.ts ---
  /**
   * Canonical emission order for format-aggregation groups. The classifier may
   * encounter types in any order; the encoder always emits groups in THIS order
   * (omitting types with no ranges), independent of which row/col surfaced them.
   *
   * Keeping the order fixed here is what makes the encoding deterministic across
   * runs and languages — every port MUST emit groups in the same order.
   */
  const TYPE_ORDER: readonly FormatType[] = [
    "IntNum",
    "FloatNum",
    "ScientificNum",
    "PercentageNum",
    "CurrencyData",
    "DateData",
    "TimeData",
    "YearData",
    "EmailData",
    "Boolean",
    "Text",
  ] as const;

  /**
   * Classification patterns, applied in priority order. The first match wins, so
   * more-specific patterns are listed first. Examples that drive the ordering:
   *   - "1900" matches both Year and Int — Year is more specific, must run first
   *   - "1.5e10" matches both Scientific and (loosely) Float — Scientific first
   *   - "$5" matches Currency, not Int — Currency comes before the numeric fallbacks
   */
  const BOOLEAN = /^(?:true|false)$/i;
  const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  const SCIENTIFIC = /^-?\d+(?:\.\d+)?[eE][+-]?\d+$/;
  const PERCENT = /^-?\d+(?:\.\d+)?%$/;
  const CURRENCY = /^-?[$€£¥]\d+(?:\.\d+)?$/;
  const DATE_ISO = /^\d{4}-\d{1,2}-\d{1,2}$/;
  const DATE_SLASH = /^\d{1,2}\/\d{1,2}\/\d{2,4}$/;
  const DATE_DASH = /^\d{1,2}-\d{1,2}-\d{2,4}$/;
  const TIME_12 = /^\d{1,2}:\d{2}(?::\d{2})?\s?(?:AM|PM|am|pm)$/;
  const TIME_24 = /^\d{1,2}:\d{2}(?::\d{2})?$/;
  const YEAR = /^(?:19|20)\d{2}$/;
  const FLOAT = /^-?(?:\d+\.\d*|\.\d+)$/;
  const INT = /^-?\d+$/;

  /**
   * Header labels that mark a column as holding years. Used by the context-aware
   * year resolver (SPEC §5.1.1). Matched case-insensitively as whole words, so
   * "yy-mm" (a month-year date header) deliberately does NOT match.
   */
  const YEAR_HEADER = /\b(?:years?|yr|yyyy|fy|fiscal\s*years?)\b/i;

  /**
   * Classify a single cell value into a format-aggregation category, by VALUE
   * ALONE. A 4-digit value in 1900–2099 is reported as a `YearData` *candidate*;
   * whether it stays a year or becomes `IntNum` is decided by context in
   * `resolveYear` (SPEC §5.1.1). Returns `null` for the empty string (the only
   * value considered empty per SPEC §3.1).
   */
  export function classify(v: string): FormatType | null {
    if (v === "") return null;
    if (BOOLEAN.test(v)) return "Boolean";
    if (EMAIL.test(v)) return "EmailData";
    if (SCIENTIFIC.test(v)) return "ScientificNum";
    if (PERCENT.test(v)) return "PercentageNum";
    if (CURRENCY.test(v)) return "CurrencyData";
    if (DATE_ISO.test(v) || DATE_SLASH.test(v) || DATE_DASH.test(v))
      return "DateData";
    if (TIME_12.test(v) || TIME_24.test(v)) return "TimeData";
    if (YEAR.test(v)) return "YearData";
    if (FLOAT.test(v)) return "FloatNum";
    if (INT.test(v)) return "IntNum";
    return "Text";
  }

  /**
   * Find the column header governing cell (r, c): the nearest non-empty cell
   * ABOVE it in the same column whose value classifies as Text (a label). Skips
   * blanks and numeric cells so a header above intervening data is still found.
   * Returns null when the column has no text label above the cell.
   */
  function nearestHeaderAbove(grid: Grid, r: number, c: number): string | null {
    for (let rr = r - 1; rr >= 0; rr--) {
      const v = grid.rows[rr]?.[c] ?? "";
      if (v === "") continue;
      if (classify(v) === "Text") return v;
    }
    return null;
  }

  /**
   * Decide whether a year *candidate* at (r, c) is really a `YearData` or an
   * ordinary `IntNum` (SPEC §5.1.1). Priority:
   *   1. Column header is the dominant signal: a year-ish header → YearData; any
   *      other header → IntNum (suppresses a stray in-range integer like a count).
   *   2. No header → column-neighbour signal: stays YearData only if EVERY other
   *      integer-valued cell in the column is also a year (1900–2099) and there is
   *      at least one such neighbour.
   *   3. Isolated in-range integer with no header and no integer neighbours →
   *      IntNum (we don't guess "year" from a lone value).
   */
  function resolveYear(grid: Grid, r: number, c: number): FormatType {
    const header = nearestHeaderAbove(grid, r, c);
    if (header !== null) {
      return YEAR_HEADER.test(header) ? "YearData" : "IntNum";
    }

    let intSiblings = 0;
    let yearSiblings = 0;
    const numRows = grid.rows.length;
    for (let rr = 0; rr < numRows; rr++) {
      if (rr === r) continue;
      const t = classify(grid.rows[rr]?.[c] ?? "");
      if (t === "YearData") {
        intSiblings++;
        yearSiblings++;
      } else if (t === "IntNum") {
        intSiblings++;
      }
    }
    if (intSiblings === 0) return "IntNum";
    return yearSiblings === intSiblings ? "YearData" : "IntNum";
  }

  type Rect = {
    type: FormatType;
    topRow: number;
    leftCol: number;
    bottomRow: number;
    rightCol: number;
  };

  /**
   * Greedy rectangular aggregation: scan the type map in row-major order; for
   * each unclaimed non-empty cell, extend as far right as the row's same-type
   * run goes, then extend down as long as every row below matches that full
   * width. Mark the rectangle's cells claimed and continue. Empty cells break
   * runs (no aggregation across gaps).
   */
  function aggregate(grid: Grid): Rect[] {
    const numRows = grid.rows.length;
    let numCols = 0;
    for (const row of grid.rows) {
      if (row.length > numCols) numCols = row.length;
    }
    if (numRows === 0 || numCols === 0) return [];

    const types: (FormatType | null)[][] = Array.from(
      { length: numRows },
      (_, r) => {
        const row = grid.rows[r] ?? [];
        return Array.from({ length: numCols }, (_, c) => classify(row[c] ?? ""));
      },
    );

    // Context-aware year resolution (SPEC §5.1.1): a value-level YearData stays a
    // year only when its column header / neighbours support it; otherwise IntNum.
    for (let r = 0; r < numRows; r++) {
      const typeRow = types[r]!;
      for (let c = 0; c < numCols; c++) {
        if (typeRow[c] === "YearData") typeRow[c] = resolveYear(grid, r, c);
      }
    }

    const claimed: boolean[][] = Array.from({ length: numRows }, () =>
      new Array<boolean>(numCols).fill(false),
    );

    const rects: Rect[] = [];

    for (let r = 0; r < numRows; r++) {
      const typeRow = types[r]!;
      const claimedRow = claimed[r]!;
      for (let c = 0; c < numCols; c++) {
        if (claimedRow[c]) continue;
        const t = typeRow[c];
        if (t == null) continue;

        // Extend right along row r.
        let w = 1;
        while (c + w < numCols && typeRow[c + w] === t && !claimedRow[c + w]) {
          w++;
        }

        // Extend down: each candidate row must be fully same-type AND unclaimed
        // across the [c, c+w) span.
        let h = 1;
        extendDown: while (r + h < numRows) {
          const nextTypes = types[r + h]!;
          const nextClaimed = claimed[r + h]!;
          for (let cc = c; cc < c + w; cc++) {
            if (nextTypes[cc] !== t || nextClaimed[cc]) break extendDown;
          }
          h++;
        }

        for (let rr = r; rr < r + h; rr++) {
          claimed[rr]!.fill(true, c, c + w);
        }

        rects.push({
          type: t,
          topRow: r,
          leftCol: c,
          bottomRow: r + h - 1,
          rightCol: c + w - 1,
        });
      }
    }

    return rects;
  }

  function rectToRange(rect: Rect, origin: Origin): string {
    const topLeft = a1(origin.row + rect.topRow, origin.col + rect.leftCol);
    if (rect.topRow === rect.bottomRow && rect.leftCol === rect.rightCol) {
      return topLeft;
    }
    const bottomRight = a1(
      origin.row + rect.bottomRow,
      origin.col + rect.rightCol,
    );
    return `${topLeft}:${bottomRight}`;
  }

  export function encodeFormatAggregation(
    grid: Grid,
    tokenCounter: TokenCounter,
  ): Encoding<FormatAggregationJson> {
    const rects = aggregate(grid);

    const byType = new Map<FormatType, string[]>();
    for (const rect of rects) {
      const ranges = byType.get(rect.type) ?? [];
      ranges.push(rectToRange(rect, grid.origin));
      byType.set(rect.type, ranges);
    }

    const groups: FormatAggregationJson["groups"] = [];
    for (const t of TYPE_ORDER) {
      const ranges = byType.get(t);
      if (!ranges || ranges.length === 0) continue;
      groups.push({ type: t, ranges });
    }

    const string = groups
      .map((g) => `${g.type}: ${g.ranges.join(",")}`)
      .join("\n");

    const json: FormatAggregationJson = {
      encoding: "format-aggregation",
      version: 0,
      origin: { row: grid.origin.row, col: grid.origin.col },
      groups,
    };

    return { string, json, tokenEstimate: tokenCounter(string) };
  }

  // --- strategies.ts ---
  /** SPEC §3.1: Phase-1 neighborhood window radius. */
  const PHASE1_K = 4;
  /** SPEC §3.1: Phase-1 heterogeneity threshold (unique ÷ non-empty). */
  const PHASE1_HET_THRESHOLD = 0.5;

  /**
   * SPEC §3.1: legacy "keep every cell" policy. Pre-Phase-1 default; retained
   * so callers can opt out of Phase-1 detection and as the simplest possible
   * conformance reference.
   */
  export const keepAllStrategy: AnchorStrategy = {
    name: "keep-all",
    detect(grid: Grid): AnchorDetection {
      const { rowCount, colCount } = gridDimensions(grid);
      const keptRows = new Set<number>();
      for (let r = 0; r < rowCount; r++) keptRows.add(r);
      const keptCols = new Set<number>();
      for (let c = 0; c < colCount; c++) keptCols.add(c);
      return { keptRows, keptCols };
    },
  };

  /**
   * SPEC §3.1: Phase-1 structural-anchor detection. Grid-only cues — per-row /
   * per-column value heterogeneity plus data-type transitions between adjacent
   * lines — feed a k-neighborhood keep window. Entirely-blank rows/columns
   * within the kept region are pruned in a final pass.
   */
  export const phase1Strategy: AnchorStrategy = {
    name: "phase1",
    detect(grid: Grid): AnchorDetection {
      const { rowCount, colCount } = gridDimensions(grid);
      if (rowCount === 0 || colCount === 0) {
        return { keptRows: new Set(), keptCols: new Set() };
      }

      const cell = (r: number, c: number): string => grid.rows[r]?.[c] ?? "";
      const type = (r: number, c: number): DataType => {
        const explicit = grid.cellMeta?.[r]?.[c]?.dataType;
        if (explicit) return explicit;
        return inferType(cell(r, c));
      };

      const anchorRows = new Set<number>();
      for (let r = 0; r < rowCount; r++) {
        const values: string[] = [];
        for (let c = 0; c < colCount; c++) values.push(cell(r, c));
        if (heterogeneity(values) >= PHASE1_HET_THRESHOLD) anchorRows.add(r);
      }
      for (let r = 1; r < rowCount; r++) {
        if (rowTypesDiffer(type, r - 1, r, colCount)) {
          anchorRows.add(r - 1);
          anchorRows.add(r);
        }
      }

      const anchorCols = new Set<number>();
      for (let c = 0; c < colCount; c++) {
        const values: string[] = [];
        for (let r = 0; r < rowCount; r++) values.push(cell(r, c));
        if (heterogeneity(values) >= PHASE1_HET_THRESHOLD) anchorCols.add(c);
      }
      for (let c = 1; c < colCount; c++) {
        if (colTypesDiffer(type, c - 1, c, rowCount)) {
          anchorCols.add(c - 1);
          anchorCols.add(c);
        }
      }

      const keptRows = expandNeighborhood(anchorRows, rowCount, PHASE1_K);
      const keptCols = expandNeighborhood(anchorCols, colCount, PHASE1_K);

      // Prune entirely-blank rows/cols within the kept region.
      for (const r of Array.from(keptRows)) {
        let hasContent = false;
        for (const c of Array.from(keptCols)) {
          if (cell(r, c) !== "") {
            hasContent = true;
            break;
          }
        }
        if (!hasContent) keptRows.delete(r);
      }
      for (const c of Array.from(keptCols)) {
        let hasContent = false;
        for (const r of Array.from(keptRows)) {
          if (cell(r, c) !== "") {
            hasContent = true;
            break;
          }
        }
        if (!hasContent) keptCols.delete(c);
      }

      return { keptRows, keptCols };
    },
  };

  function gridDimensions(grid: Grid): { rowCount: number; colCount: number } {
    const rowCount = grid.rows.length;
    let colCount = 0;
    for (const row of grid.rows) {
      if (row.length > colCount) colCount = row.length;
    }
    return { rowCount, colCount };
  }

  const NUMERIC_RE = /^-?\d+(\.\d+)?$/;

  /**
   * SPEC §3.1: when `cellMeta.dataType` is absent we infer from the raw text.
   * Only three buckets in v0 so every language agrees byte-for-byte: empty,
   * a strict decimal, or text.
   */
  function inferType(value: string): DataType {
    if (value === "") return "empty";
    if (NUMERIC_RE.test(value)) return "number";
    return "text";
  }

  function heterogeneity(values: string[]): number {
    let nonEmpty = 0;
    const seen = new Set<string>();
    for (const v of values) {
      if (v === "") continue;
      nonEmpty++;
      seen.add(v);
    }
    if (nonEmpty === 0) return 0;
    return seen.size / nonEmpty;
  }

  function rowTypesDiffer(
    type: (r: number, c: number) => DataType,
    rA: number,
    rB: number,
    colCount: number,
  ): boolean {
    for (let c = 0; c < colCount; c++) {
      if (type(rA, c) !== type(rB, c)) return true;
    }
    return false;
  }

  function colTypesDiffer(
    type: (r: number, c: number) => DataType,
    cA: number,
    cB: number,
    rowCount: number,
  ): boolean {
    for (let r = 0; r < rowCount; r++) {
      if (type(r, cA) !== type(r, cB)) return true;
    }
    return false;
  }

  function expandNeighborhood(
    anchors: ReadonlySet<number>,
    size: number,
    k: number,
  ): Set<number> {
    const kept = new Set<number>();
    for (const a of Array.from(anchors)) {
      const lo = Math.max(0, a - k);
      const hi = Math.min(size - 1, a + k);
      for (let i = lo; i <= hi; i++) kept.add(i);
    }
    return kept;
  }

  export function resolveStrategy(
    s: AnchorStrategyName | AnchorStrategy | undefined,
  ): AnchorStrategy {
    if (s === undefined) return phase1Strategy;
    if (typeof s === "string") {
      switch (s) {
        case "keep-all":
          return keepAllStrategy;
        case "phase1":
          return phase1Strategy;
      }
    }
    return s;
  }

  // --- compress.ts ---
  /**
   * SPEC §6.2: extend an encoding's `.string` with the chart block (if any) and
   * re-measure `.tokenEstimate` over the extended form. The encoding's `.json`
   * is unchanged — chart data only lives in the string + the top-level echo.
   */
  function withCharts<T>(
    encoding: Encoding<T>,
    chartBlock: string,
    tokenCounter: TokenCounter,
  ): Encoding<T> {
    if (chartBlock === "") return encoding;
    const string = appendChartBlock(encoding.string, chartBlock);
    return { string, json: encoding.json, tokenEstimate: tokenCounter(string) };
  }

  export function compress(
    grid: Grid,
    options: CompressOptions = {},
  ): CompressResult {
    const strategy = resolveStrategy(options.anchorStrategy);
    const detection = strategy.detect(grid);
    const tokenCounter = options.tokenCounter ?? estimateTokens;
    const chartBlock = renderChartBlock(grid.charts);
    return {
      encodings: {
        anchor: withCharts(
          encodeAnchor(grid, detection, tokenCounter),
          chartBlock,
          tokenCounter,
        ),
        invertedIndex: withCharts(
          encodeInvertedIndex(grid, tokenCounter),
          chartBlock,
          tokenCounter,
        ),
        formatAggregation: withCharts(
          encodeFormatAggregation(grid, tokenCounter),
          chartBlock,
          tokenCounter,
        ),
      },
      charts: grid.charts ? [...grid.charts] : [],
      rawBaseline: { tokenEstimate: tokenCounter(vanillaEncode(grid)) },
    };
  }
}

// ---------------------------------------------------------------------------
// Host glue (hand-written — NOT generated). Maps the ExcelScript host model to
// the bundled SheetCompressorInternal core and back. Everything host-touching
// is defensive (try/catch) so a quirky workbook degrades rather than throws.
// ---------------------------------------------------------------------------

/**
 * Map an ExcelScript chart-type tag to the SPEC's 6-value ChartType. The
 * runtime enum has dozens of members (columnClustered, lineMarkers, pieExploded
 * …); we bucket by substring so new variants map sensibly, defaulting to
 * "other".
 */
function mapChartType(raw: string): SheetCompressorInternal.ChartType {
  const t = (raw || "").toLowerCase();
  if (t.indexOf("bar") !== -1) return "bar";
  if (t.indexOf("column") !== -1) return "bar"; // column charts are bar-family
  if (t.indexOf("line") !== -1) return "line";
  if (t.indexOf("pie") !== -1 || t.indexOf("doughnut") !== -1) return "pie";
  if (t.indexOf("scatter") !== -1 || t.indexOf("xy") !== -1) return "scatter";
  if (t.indexOf("area") !== -1) return "area";
  return "other";
}

/**
 * Best-effort chart extraction from worksheet metadata → ChartDescriptor[].
 * Every host call is wrapped: a chart that throws on any accessor still yields
 * a partial descriptor rather than aborting the whole run. The optional base64
 * render (getImage) is intentionally NOT attached to the descriptor — it is not
 * part of the SPEC ChartDescriptor and would bloat the prompt. Flip
 * `includeImage` and read `images` if a caller wants it.
 */
function extractCharts(
  sheet: ExcelScript.Worksheet,
  includeImage: boolean,
): { charts: SheetCompressorInternal.ChartDescriptor[]; images: { name: string; base64: string }[] } {
  const charts: SheetCompressorInternal.ChartDescriptor[] = [];
  const images: { name: string; base64: string }[] = [];
  let hostCharts: ExcelScript.Chart[] = [];
  try {
    hostCharts = sheet.getCharts();
  } catch (e) {
    return { charts, images };
  }
  for (const chart of hostCharts) {
    let name = "";
    try {
      name = chart.getName();
    } catch (e) {
      name = "";
    }

    let type: SheetCompressorInternal.ChartType = "other";
    try {
      type = mapChartType(String(chart.getChartType()));
    } catch (e) {
      type = "other";
    }

    // anchorRange is best-effort: the ExcelScript Chart surface does not expose
    // a clean anchor address, so we leave it empty when unavailable. The SPEC
    // treats anchorRange as opaque, so an empty string renders as CHART(type)@.
    let anchorRange = "";

    let title: string | undefined = undefined;
    try {
      const text = chart.getTitle().getText();
      if (text) title = text;
    } catch (e) {
      title = undefined;
    }

    const descriptor: SheetCompressorInternal.ChartDescriptor = { name, type, anchorRange };
    if (title !== undefined) descriptor.title = title;
    charts.push(descriptor);

    if (includeImage) {
      try {
        const base64 = chart.getImage();
        if (base64) images.push({ name, base64 });
      } catch (e) {
        // image render is optional; ignore failures.
      }
    }
  }
  return { charts, images };
}

/**
 * Entry point for Excel Automate. Reads the target sheet's used range into a
 * Grid (origin from the range's 0-indexed row/col + 1), extracts chart
 * descriptors from host metadata, runs the bundled compress(), and returns all
 * three encodings (string + json + tokenEstimate) plus the chart echo and the
 * raw baseline. Pass `includeImage = true` to also return base64 chart renders.
 */
function main(
  workbook: ExcelScript.Workbook,
  sheetName?: string,
  includeImage: boolean = false,
): {
  sheetName: string;
  origin: { row: number; col: number };
  encodings: {
    anchor: { string: string; json: string; tokenEstimate: number };
    invertedIndex: { string: string; json: string; tokenEstimate: number };
    formatAggregation: { string: string; json: string; tokenEstimate: number };
  };
  charts: SheetCompressorInternal.ChartDescriptor[];
  rawBaseline: { tokenEstimate: number };
  images: { name: string; base64: string }[];
} {
  const sheet = sheetName
    ? workbook.getWorksheet(sheetName)
    : workbook.getActiveWorksheet();
  if (!sheet) throw new Error("Worksheet not found: " + (sheetName ?? "(active)"));

  const range = sheet.getUsedRange();
  // An empty sheet has no used range; treat as an empty grid at A1.
  const texts: string[][] = range ? range.getTexts() : [];
  const origin = {
    row: (range ? range.getRowIndex() : 0) + 1,
    col: (range ? range.getColumnIndex() : 0) + 1,
  };

  const extracted = extractCharts(sheet, includeImage);

  // Charts ride on the Grid (SPEC §1); compress() reads them from there and
  // appends the CHART(...) tokens + echoes them on result.charts (SPEC §6).
  const grid: SheetCompressorInternal.Grid = {
    rows: texts,
    origin,
    charts: extracted.charts,
  };

  const result = SheetCompressorInternal.compress(grid);

  const enc = (e: SheetCompressorInternal.Encoding<unknown>) => ({
    string: e.string,
    json: JSON.stringify(e.json, null, 2) + "\n",
    tokenEstimate: e.tokenEstimate,
  });

  return {
    sheetName: sheet.getName(),
    origin,
    encodings: {
      anchor: enc(result.encodings.anchor),
      invertedIndex: enc(result.encodings.invertedIndex),
      formatAggregation: enc(result.encodings.formatAggregation),
    },
    charts: result.charts,
    rawBaseline: result.rawBaseline,
    images: extracted.images,
  };
}