using Xunit;

namespace AcDream.App.Tests.Rendering;

/// <summary>
/// Serializes every test class that shares the camera/render family of
/// <b>process-global mutable statics</b>. xUnit runs distinct test classes in
/// PARALLEL by default, and these statics live on the process, not on the test
/// — so two classes running concurrently observe each other's writes.
///
/// <para>
/// The per-class <c>try</c>/<c>finally</c> save/restore blocks are correct
/// <i>within</i> a class and remain necessary — but they are not sufficient.
/// A <c>finally</c> only bounds the mutation in TIME along its own thread; it
/// cannot stop another class from reading the static inside that window. Worse,
/// two overlapping save/restore pairs can interleave so the second restore
/// writes back the FIRST one's temporary value, leaving the global permanently
/// wrong for the rest of the run. Serializing the sharers is what actually makes
/// each class's <c>finally</c> sufficient.
/// </para>
///
/// <para>Three distinct globals are covered, and every one of them is a shared
/// edge between at least two classes in this collection:</para>
/// <list type="bullet">
///   <item><description><c>AcDream.Core.Rendering.CameraDiagnostics</c> —
///   <c>AlignToSlope</c>, <c>CollideCamera</c>, <c>TranslationStiffness</c>,
///   <c>RotationStiffness</c>, <c>UseRetailChaseCamera</c>. Read by
///   <c>RetailChaseCamera.Update</c>, <c>CameraController.Active</c>,
///   <c>CameraFrameController</c>, <c>WorldRenderFrameBuilder</c> and
///   <c>MouseLookController</c>.</description></item>
///   <item><description><c>AcDream.Core.Rendering.RenderingDiagnostics.ProbeFlapEnabled</c>
///   — written by <c>CornerFloodReplayTests</c> and
///   <c>Issue181WallPressEquilibriumTests</c>.</description></item>
///   <item><description><c>System.Console.Out</c> — redirected via
///   <c>Console.SetOut</c> by those same two classes to capture probe output.
///   Interleaved redirection can restore a DISPOSED <c>StringWriter</c> as the
///   process-wide <c>Console.Out</c>, which then throws in unrelated
///   tests.</description></item>
/// </list>
///
/// <para>
/// Membership is deliberately narrow: only classes that write one of these
/// globals, or that drive production code which READS a knob another member
/// mutates away from its default (<c>RetailChaseCameraTests</c> sets
/// <c>AlignToSlope</c> and <c>CollideCamera</c> to <see langword="false"/>;
/// the <c>UseRetailChaseCamera</c> writers set it to <see langword="false"/>).
/// Classes that merely construct a <c>CameraController</c> without a retail
/// chase camera are NOT members — their reads are insensitive.
/// </para>
///
/// <para>
/// Marker only, no collection fixture: each member still needs its own
/// per-test values (several are <c>[Theory]</c> cases that set different knobs
/// per case), so a fixture cannot own the save/restore without rewriting every
/// member's internals. The existing per-test <c>finally</c> blocks already
/// return the defaults; this attribute supplies the mutual exclusion they were
/// missing. Follows the <c>WorldEnvironmentControllerCollection</c> precedent.
/// </para>
///
/// <para>Evidence + history: <c>docs/ISSUES.md</c> #251.</para>
/// </summary>
[CollectionDefinition(Name)]
public sealed class CameraDiagnosticsCollection
{
    public const string Name = "Camera diagnostics globals";
}