All committers have signed the CLA.

Sorry this would be breaking and is therefore not acceptable.

Maybe we can have a non-breaking way (however, I doubt that - as I guess you explicitly want the interface to implement it).

Why do you consider this a breaking change? It's not affecting any existing functionality.

It changes a public interface. So if you upgrade your code will not compile (assuming you implement that interface somewhere). If you just swap you'll end up with an exception.

So it requires changes which is by definition a breaking change.

We could maybe overcome this with default interface implementation can't we?

In general default interface methods could help (up to some extend), but as they require runtime support (starting with .NET Core 3.0, i.e., .NET standard 2.1) it would be another breaking change (see: https://github.com/AngleSharp/AngleSharp/blob/devel/src/AngleSharp.nuspec - it's .NET Standard 2.0 that we support in the lib).

Would u consider target-specific implementation?

    public interface IHtmlCollection<T>
#if NET8_0_OR_GREATER
        : IReadOnlyList<T>
#endif

For example (all tests pass after changing only this file to the following):

namespace AngleSharp.Dom;

using AngleSharp.Attributes;
using System;
using System.Collections.Generic;

/// <summary>
/// This type represents a set of space-separated tokens.
/// </summary>
[DomName("DOMTokenList")]
public interface ITokenList :
#if NET8_0_OR_GREATER
    IReadOnlyList<String>
#else
    IEnumerable<String>
#endif
{
    /// <summary>
    /// Gets the number of contained tokens.
    /// </summary>
    [DomName("length")]
    Int32 Length { get; }

    /// <summary>
    /// Gets an item in the list by its index.
    /// </summary>
    /// <param name="index">The index of the item.</param>
    /// <returns>The item at the specified index.</returns>
    [DomName("item")]
    [DomAccessor(Accessors.Getter)]
#if NET8_0_OR_GREATER
    new
#endif
    String this[Int32 index] { get; }

    /// <summary>
    /// Returns true if the underlying string contains a token, otherwise
    /// false.
    /// </summary>
    /// <param name="token">The token to search for.</param>
    /// <returns>The result of the search.</returns>
    [DomName("contains")]
    Boolean Contains(String token);

    /// <summary>
    /// Adds some tokens to the underlying string.
    /// </summary>
    /// <param name="tokens">A list of tokens to add.</param>
    [DomName("add")]
    void Add(params String[] tokens);

    /// <summary>
    /// Remove some tokens from the underlying string.
    /// </summary>
    /// <param name="tokens">A list of tokens to remove.</param>
    [DomName("remove")]
    void Remove(params String[] tokens);

    /// <summary>
    /// Removes the specified token from string and returns false.
    /// If token doesn't exist it's added and the function returns true.
    /// </summary>
    /// <param name="token">The token to toggle.</param>
    /// <param name="force"></param>
    /// <returns>
    /// True if the token has been added, otherwise false.
    /// </returns>
    [DomName("toggle")]
    Boolean Toggle(String token, Boolean force = false);


#if NET8_0_OR_GREATER
    Int32 IReadOnlyCollection<String>.Count => Length;
#endif
}

I think it might be an option; but it definitely needs further testing (for instance the swap test; can the lib just be changed or is a re-compilation necessary; which also indicates a breaking change - this time not API, but ABI).

I ran a manual test I created a new project with a project reference to AngleSharp.Core then replaced only the AngleSharp.Core.dll file with the output of the compilation containing the IReadOnlyList change

I ran a manual test I created a new project with a project reference to AngleSharp.Core then replaced only the AngleSharp.Core.dll file with the output of the compilation containing the IReadOnlyList change

Did the project contain a reference / a class defined to, e.g., implement ITokenList? Because this is the scenario we are looking for.

Yes, it's a console app that adds a List<String> subclass that implements ITokenList and makes use of the implementation adding values and accessing it's Length and Count properties, all based on the current devel branch that only implements IEnumerable<String>.

After replacing AngleSharp.dll in the console folder with the new one compiled after introducing the interface implementation change it still works as intended.

Then let's do it :)

FYI
There's one test failing, but it also fails on the devel branch.

The reason we're 'overriding' it is to allow for the documentation and attributes.

The reason we're 'overriding' it is to allow for the documentation and attributes.

I know that. I have nothing against the reason; I have something against hiding and I'd like to avoid it (as written).

Fixed

Both systems are failing; any reason why you still use the list and not a collection? I don't really get it. As it stands the previous iteration was better imho.

Bear with me just a bit more please flo 😁
Reason IReadOnlyList would be preferred is because IHtmlCollection exposes all features of it just in a different name. I mean, if it works why not include it.

BTW, I've learned a bit of the code in the CSS selector, a true masterpiece!