"""The standard window grid. Fixed pipeline helper; do not edit."""

from __future__ import annotations

import numpy as np


def window_starts(
    n_samples: int, seg_len: int, hop_samples: int
) -> np.ndarray:
    """Start indices of the decision windows over ``n_samples``.

    Window ``k`` (0-based) spans ``starts[k] : starts[k] + seg_len``;
    the entries before ``k`` are the previous windows of the trial.

    Raises when ``seg_len`` or ``hop_samples`` leaves the legal range
    (both at least 1 sample, ``hop_samples <= seg_len``; overlapping
    windows included, gaps not). Returns an empty array when no full window
    fits in ``n_samples``.
    """
    if seg_len < 1 or hop_samples < 1 or hop_samples > seg_len:
        raise ValueError(
            "seg_len is %d and hop_samples is %d; both must be at least "
            "1 sample and hop_samples must not exceed seg_len. "
            "Overlapping windows are allowed, gaps are not."
            % (seg_len, hop_samples)
        )
    n_windows = (n_samples - seg_len) // hop_samples + 1
    if n_windows < 1:
        return np.zeros(0, dtype=np.int64)
    return np.arange(n_windows) * hop_samples
