osmgl 0.7.2 → 0.7.3

package/dist/osmgl.d.cts

@@ -4350,6 +4350,14 @@ interface QualityProfile {
     simpleGeometry: boolean;
 }
 declare const qualityProfile: (name: QualityName) => QualityProfile;
+/**
+ * Класс GPU по строке рендерера.
+ *
+ * `unknown` — не признак слабости, а честное «не знаем»: Safari отдаёт всем одну и ту же строку,
+ * Firefox её огрубляет, а Tor и Brave в строгом режиме не отдают вовсе. Поэтому неизвестность НЕ
+ * должна ничего решать — она просто оставляет вывод за остальными признаками.
+ */
+type GpuClass = 'software' | 'weak' | 'strong' | 'unknown';
 /** То, из чего делается вывод. Вынесено в аргумент, чтобы это можно было проверить тестом. */
 interface DeviceHints {
     /** Число логических ядер (`navigator.hardwareConcurrency`). */
@@ -4359,7 +4367,22 @@ interface DeviceHints {
     /** Мобильное устройство: грубый указатель или явный признак от браузера. */
     mobile: boolean;
     devicePixelRatio: number;
+    /** Класс видеокарты по строке рендерера, если её удалось прочитать. */
+    gpu?: GpuClass;
 }
+/**
+ * Класс GPU по строке `UNMASKED_RENDERER_WEBGL`.
+ *
+ * Ровно тот же приём, на котором стоит `detect-gpu`: строка рендерера — единственное, что браузер
+ * говорит о видеокарте, не заставляя ничего рисовать. Полноценная база моделей с замерами (как у
+ * `detect-gpu`) сюда не поместится и устареет, поэтому распознаём только то, что решает исход:
+ * программный растеризатор, заведомо слабое встроенное видео и заведомо сильные дискретные чипы.
+ * Всё остальное — `unknown`, и решают ядра с памятью.
+ *
+ * Мерить бенчмарком на старте по-прежнему нельзя: это сотни миллисекунд ровно там, где важна первая
+ * отрисовка. Строка бесплатна.
+ */
+declare function classifyRenderer(renderer: string): GpuClass;
 /**
  * Профиль по признакам устройства.
  *
@@ -4381,6 +4404,101 @@ declare function deviceHints(): DeviceHints;
 declare function clampPixelRatio(cssWidth: number, cssHeight: number, devicePixelRatio: number, profile: QualityProfile): number;
 /** Следующий профиль вниз или null, если ниже некуда. */
 declare function nextQualityDown(name: QualityName): QualityName | null;
+/** Решение контроллера: на какую ступень перейти и в какую сторону. */
+interface QualityChange {
+    to: QualityName;
+    direction: 'up' | 'down';
+    /** Доля тяжёлых кадров, на которой решение принято, — для сообщения в консоль. */
+    share: number;
+}
+/**
+ * Кто решает, менять ли ступень качества.
+ *
+ * ЗАЧЕМ ОТДЕЛЬНЫМ КЛАССОМ. Логика тут вся в состоянии — окно кадров, счётчики попыток, прогрев, —
+ * и ошибка в ней не падает, а проявляется миганием теней у пользователя. Отдельно её видно и можно
+ * проверить тестом, подавая кадры прямо (см. `tests/quality.test.mjs`).
+ *
+ * УСТРОЙСТВО. Вниз — быстро и по доле тяжёлых кадров: тормоза видно сразу. Вверх — медленно, с
+ * ГИСТЕРЕЗИСОМ (порог подъёма на порядок ниже порога спуска) и с ХРАПОВИКОМ: каждая неудачная
+ * попытка удваивает требуемое время спокойствия, а после второй ступень закрывается насовсем.
+ * Именно храповик даёт главное свойство — качели ГАРАНТИРОВАННО затухают, а не ходят вечно.
+ *
+ * Так же устроены адаптивные масштабы разрешения в игровых движках: гистерезис против дребезга и
+ * ограниченное число проб вверх, чтобы «подкачка» качества не стала заметной сама по себе.
+ */
+declare class QualityGovernor {
+    private current;
+    private ceiling;
+    /** Кадр дольше этого — тяжёлый. */
+    private readonly slowMs;
+    /** Кадр дольше этого весит втрое: сотня миллисекунд — это не «немного не успели». */
+    private readonly verySlowMs;
+    private ring;
+    private at;
+    private sum;
+    private filled;
+    /** Кадров подряд на текущей ступени (после прогрева). */
+    private steady;
+    private warmup;
+    /** Неудачные попытки подъёма на ступень: имя → сколько раз сорвались. */
+    private attempts;
+    /** Пришли ли мы на текущую ступень подъёмом — только такой срыв считается неудачей. */
+    private arrivedByUp;
+    /** Последние измерения — запасная оценка шага развёртки. См. [[threshold]]. */
+    private recent;
+    private recentAt;
+    private recentFilled;
+    /** Измеренный шаг развёртки экрана, мс. Ноль — не измерен. */
+    private refreshMs;
+    constructor(current: QualityName, ceiling: QualityName, 
+    /** Кадр дольше этого — тяжёлый. */
+    slowMs: number, 
+    /** Кадр дольше этого весит втрое: сотня миллисекунд — это не «немного не успели». */
+    verySlowMs: number);
+    /** Потолок, до которого разрешено подниматься сейчас. Опускается сам, когда ступень не даётся. */
+    get limit(): QualityName;
+    /** Сменили ступень снаружи (`setQuality`) — начать наблюдение заново. */
+    reset(current: QualityName, ceiling: QualityName): void;
+    /**
+     * Очередной кадр. `busy` — едут ли тайлы: пока едут, кадры не считаются вовсе.
+     *
+     * Зум и панорама всегда дают всплеск — приезжают и разбираются новые тайлы, — и на нём порог
+     * набирался за пару секунд у любой карты. Мерить надо УСТОЯВШУЮСЯ стоимость, а не стоимость
+     * загрузки.
+     */
+    frame(frameMs: number, busy: boolean): QualityChange | null;
+    /**
+     * Порог «тяжёлого кадра» с поправкой на ЭКРАН.
+     *
+     * Мерой служит интервал между кадрами, а порог был жёсткий — 32 мс, «медленнее тридцати в
+     * секунду». Но тридцать в секунду бывает и потолком САМОГО экрана: развёртка 30 Гц, режим
+     * энергосбережения, композитор, ограничивший вкладку. Там интервал ровно 33 мс не потому, что
+     * карта не успевает, а потому, что чаще показывать некуда, — и здоровая машина уезжала до
+     * `minimal`, а на границе порога ещё и раскачивалась. Проверено: на широком окне шаг оказался
+     * ровно 33 мс, и профиль сходил на три ступени за шесть секунд.
+     *
+     * Шаг развёртки берём ИЗМЕРЕННЫЙ (`setRefresh`), а не выведенный из тех же кадров. Вывод по
+     * минимуму здесь принципиально неоднозначен: машина, ровно пригвождённая к 40 мс, неотличима от
+     * экрана на 25 Гц — в обоих случаях все интервалы одинаковы. Разводит их только замер на ПУСТЫХ
+     * кадрах в начале жизни карты, когда рисовать ещё нечего и частота кадров равна развёртке.
+     *
+     * Минимум по недавним кадрам остаётся запасным вариантом — на случай, если замер не удался.
+     * Порог ниже исходного не опускается: на экране 120 Гц требовать от карты 120 кадров незачем.
+     */
+    private threshold;
+    /**
+     * Сообщить измеренный шаг развёртки экрана (мс между кадрами при пустой сцене).
+     *
+     * Заведомо неправдоподобное игнорируем: быстрее 240 Гц экранов у нас нет, а всё, что медленнее
+     * 20 кадров в секунду, — это уже не развёртка, а неудавшийся замер.
+     */
+    setRefresh(ms: number): void;
+    private down;
+    private up;
+    private moveTo;
+    /** Забыть накопленное: после смены ступени прежние кадры относятся к другому профилю. */
+    private restart;
+}
 
 /**
  * Кусок предка, приходящийся на этот тайл: сдвиг и масштаб текстурной
@@ -5534,16 +5652,8 @@ declare class Map$1 extends Evented<MapEvents> {
      * собой заменяли, — см. `setObjects3DEnabled`.
      */
     private objects3dEnabled;
-    /** Кадры подряд, не уложившиеся в бюджет, — счётчик для понижения профиля. */
-    /** Кольцо весов кадров окна: 0 — уложился, 1 — тяжёлый, 3 — очень тяжёлый. */
-    private readonly frameRing;
-    private ringAt;
-    private ringSum;
-    private ringFilled;
-    /** Кадров на текущей ступени — чтобы не проситься выше сразу после смены. */
-    private steadyFrames;
-    /** Профиль, выбранный по железу: выше него не поднимаемся никогда. */
-    private qualityCeiling;
+    /** Кто решает, менять ли ступень качества. Вся логика окна и храповика — в нём. */
+    private governor;
     /** Время прошлого кадра и сколько кадров идёт подряд — для честного замера. */
     private lastFrameAt;
     private continuousFrames;
@@ -5554,6 +5664,19 @@ declare class Map$1 extends Evented<MapEvents> {
     /** Слепок прошлого набора этажей — чтобы не слать событие каждый кадр. */
     private lastIndoorKey;
     constructor(options: MapOptions);
+    /**
+     * Замерить шаг развёртки экрана — по пустым кадрам в самом начале жизни карты.
+     *
+     * Автоснижение судит о тормозах по интервалу между кадрами, и без этого числа сравнивать его не
+     * с чем. Отдельный замер нужен потому, что по рабочим кадрам развёртку не вычислить: экран на
+     * 30 Гц и машина, ровно вдвое не успевающая на 60 Гц, дают одинаковые 33 мс. А вот пока рисовать
+     * нечего — тайлы ещё едут, сцена пуста, — частота кадров равна развёртке, и это тот единственный
+     * момент, когда её видно.
+     *
+     * Обработчик НИЧЕГО не рисует: он только запоминает отметки времени. Своих кадров он не заказывает
+     * сверх этих двенадцати и заканчивается за пятую долю секунды.
+     */
+    private measureRefresh;
     private initGL;
     private initSource;
     /** Имя источника размещений 3D-объектов (если они вообще включены). */
@@ -5826,10 +5949,9 @@ declare class Map$1 extends Evented<MapEvents> {
      *
      * Определение по признакам устройства ошибается в обе стороны: телефон с
      * восемью ядрами может нести слабый GPU, а браузер — врать про плотность.
-     * Поэтому профиль ещё и проверяется делом. Понижаем только ПОДРЯД идущие
-     * тяжёлые кадры: одиночные всплески даёт и сборка мусора, и подъезд тайлов.
-     * Обратно вверх не поднимаемся — качели «плохо → хорошо → плохо» заметнее,
-     * чем стабильно работающая карта.
+     * Поэтому профиль ещё и проверяется делом. Решение принимает `QualityGovernor` — там же и
+     * защита от качелей: гистерезис, прогрев после смены и храповик на попытки подъёма. Здесь
+     * остаётся только применить решение.
      *
      * ДВА ОГРАНИЧЕНИЯ, без которых от этого механизма больше вреда, чем пользы.
      *
@@ -5837,17 +5959,15 @@ declare class Map$1 extends Evented<MapEvents> {
      * геометрии. Разрешение пользователь видит сразу и целиком: подписи и значки после понижения
      * рисуются в буфер меньше экрана, браузер растягивает его обратно, и карта становится мыльной.
      * Упрощение геометрии отнимает у поверхностей фаску, подъём и скругление — приподнятый газон
-     * становится плоским пятном. Обратно вверх мы не поднимаемся, значит и то и другое осталось бы
-     * навсегда. Режем РАБОТУ (детализацию, тени, число тайлов и воркеров) — её потерю видно куда
-     * меньше. Так же поступают MapLibre и Mapbox: `pixelRatio` у них не адаптивный.
+     * становится плоским пятном. Обратно эти две вещи не поднимаются, значит и то и другое осталось
+     * бы навсегда. Режем РАБОТУ (детализацию, тени, число тайлов и воркеров) — её потерю видно куда
+     * меньше, и она обратима. Так же поступают MapLibre и Mapbox: `pixelRatio` у них не адаптивный.
      *
      * Второе: пока едут тайлы, кадры не считаются вовсе. Зум и панорама всегда
      * дают всплеск — приезжают и разбираются новые тайлы, — и на нём порог
      * набирался за пару секунд у любой карты. Мерить надо УСТОЯВШУЮСЯ стоимость,
      * а не стоимость загрузки.
      */
-    /** Забыть накопленное: после смены ступени прежние кадры относятся к другому профилю. */
-    private resetFrameWindow;
     private checkFrameBudget;
     getShadows(): ShadowSettings;
     /**
@@ -5985,4 +6105,4 @@ declare class Map$1 extends Evented<MapEvents> {
     destroy(): void;
 }
 
-export { type AnimationOptions, AssetLoader, type AssetLoaderOptions, BASE_SOURCE, BUILDING_HEIGHT_SCALE, BUILDING_POS_SCALE, BUILDING_VERTEX_STRIDE, type BuildingHit, type BuildingsMesh, CITY_STYLE, type CameraOptions, Circle, type CircleOptions, type CoverOptions, DEFAULT_ICONS, DEFAULT_LIGHT, DEFAULT_SHADOWS, DEFAULT_SKY, DEFAULT_STYLE, DepthTarget, type DeviceHints, EARTH_CIRCUMFERENCE, FILL_VERTEX_STRIDE, type Filter, type FitBoundsOptions, type FitViewport, type FogPlanes, GLOBE_MAX_PITCH, GLOBE_ZOOM_MAX, GLOBE_ZOOM_MIN, GLYPH_BORDER, GLYPH_SIZE, GROUND_SCALE, GeomType, type GestureOptions, type Glyph, type GlyphMetric, GlyphSource, GroundArrows, IconSource, IndoorMask, type Interpolated, LEVEL_LIMIT, LINE_VERTEX_STRIDE, type LayerPlan, LayerRenderer, type LightSpec, type LinePlacement, type LngLat, LngLatBounds, type LngLatLike, MAX_LATITUDE, MODEL_VERTEX_STRIDE, Map$1 as Map, type MapEvents, MapObject, type MapObjectOptions, type MapOptions, Marker, type MarkerOptions, Model, ModelLayer, type ModelMesh, type ModelOptions, type ModelPrimitive, ObjectManager, type ObjectPaint, type ObjectPart, type Padding, type PlacedGlyph, type PlacedSymbol, Polygon, type PolygonOptions, Polyline, type PolylineOptions, type PolylineSegment, Popup, type PopupOptions, type Projection, type QualityName, type QualityProfile, RELIEF_STYLE, RUNTIME_FILL_STRIDE, RUNTIME_LINE_STRIDE, RasterSource, type RasterSourceOptions, RasterTile, type RoundOptions, type RuntimeMesh, SDF_EDGE, SDF_PX, SOFT_STYLE, SPLIT_SEP, SURFACE_CUT_BLEED, SURFACE_LEVEL_SCALE, SURFACE_VERTEX_STRIDE, type ScreenPoint$1 as ScreenPoint, SdfAtlas, type ShadowSettings, type SkySpec, Style, type StyleLayerSpec, type StyleSpec, type SymbolHit, SymbolRenderer, THEMES, TILE_SIZE, type ThemeSpec, TileID, Transform, VectorTile, VectorTileFeature, VectorTileLayer, abbreviateStreet, addGround, altitudeFromMercatorZ, applyTheme, arrowLabelOffset, arrowVertices, buildRuntimeFill, buildRuntimeLine, cameraForBounds, circumferenceAtLatitude, clampLat, clampPixelRatio, clipLineToRect, coordinateDigits, coveringTiles, createGround, Map$1 as default, deviceHints, distToSegment, evaluateColor, evaluateNumber, extractFeature, featureLevel, fillFootprint, fogPlanes, footprintOf, formatHash, generateBuildings, generateFill, generateLine, generateSurface, generateSymbols, globeBasis, globeFlatMix, globeRadius, globeToLocal, groundAt, iconRotation, insideFootprint, latFromMercatorY, lngFromMercatorX, lngLatToUnit, matchesFilter, mercatorMetersPerTile, mercatorX, mercatorY, mercatorZFromAltitude, metersPerPixel, metersPerTile, nextQualityDown, parseGlb, parseGlbAsync, parseGlyphs, parseHash, patchUV, pickBuilding, pickFill, pitchIntent, pixelsPerMeter, placeAlongLine, pointInRing, qualityFor, qualityProfile, raySphere, resolveTemplate, roundRing, sdfFromAlpha, shapeText, splitBucketKey, splitByGround, splitPolygons, styleWithTheme, tileOriginMeters, tileUrl, toLngLat, unitToLngLat, worldSize };
+export { type AnimationOptions, AssetLoader, type AssetLoaderOptions, BASE_SOURCE, BUILDING_HEIGHT_SCALE, BUILDING_POS_SCALE, BUILDING_VERTEX_STRIDE, type BuildingHit, type BuildingsMesh, CITY_STYLE, type CameraOptions, Circle, type CircleOptions, type CoverOptions, DEFAULT_ICONS, DEFAULT_LIGHT, DEFAULT_SHADOWS, DEFAULT_SKY, DEFAULT_STYLE, DepthTarget, type DeviceHints, EARTH_CIRCUMFERENCE, FILL_VERTEX_STRIDE, type Filter, type FitBoundsOptions, type FitViewport, type FogPlanes, GLOBE_MAX_PITCH, GLOBE_ZOOM_MAX, GLOBE_ZOOM_MIN, GLYPH_BORDER, GLYPH_SIZE, GROUND_SCALE, GeomType, type GestureOptions, type Glyph, type GlyphMetric, GlyphSource, type GpuClass, GroundArrows, IconSource, IndoorMask, type Interpolated, LEVEL_LIMIT, LINE_VERTEX_STRIDE, type LayerPlan, LayerRenderer, type LightSpec, type LinePlacement, type LngLat, LngLatBounds, type LngLatLike, MAX_LATITUDE, MODEL_VERTEX_STRIDE, Map$1 as Map, type MapEvents, MapObject, type MapObjectOptions, type MapOptions, Marker, type MarkerOptions, Model, ModelLayer, type ModelMesh, type ModelOptions, type ModelPrimitive, ObjectManager, type ObjectPaint, type ObjectPart, type Padding, type PlacedGlyph, type PlacedSymbol, Polygon, type PolygonOptions, Polyline, type PolylineOptions, type PolylineSegment, Popup, type PopupOptions, type Projection, type QualityChange, QualityGovernor, type QualityName, type QualityProfile, RELIEF_STYLE, RUNTIME_FILL_STRIDE, RUNTIME_LINE_STRIDE, RasterSource, type RasterSourceOptions, RasterTile, type RoundOptions, type RuntimeMesh, SDF_EDGE, SDF_PX, SOFT_STYLE, SPLIT_SEP, SURFACE_CUT_BLEED, SURFACE_LEVEL_SCALE, SURFACE_VERTEX_STRIDE, type ScreenPoint$1 as ScreenPoint, SdfAtlas, type ShadowSettings, type SkySpec, Style, type StyleLayerSpec, type StyleSpec, type SymbolHit, SymbolRenderer, THEMES, TILE_SIZE, type ThemeSpec, TileID, Transform, VectorTile, VectorTileFeature, VectorTileLayer, abbreviateStreet, addGround, altitudeFromMercatorZ, applyTheme, arrowLabelOffset, arrowVertices, buildRuntimeFill, buildRuntimeLine, cameraForBounds, circumferenceAtLatitude, clampLat, clampPixelRatio, classifyRenderer, clipLineToRect, coordinateDigits, coveringTiles, createGround, Map$1 as default, deviceHints, distToSegment, evaluateColor, evaluateNumber, extractFeature, featureLevel, fillFootprint, fogPlanes, footprintOf, formatHash, generateBuildings, generateFill, generateLine, generateSurface, generateSymbols, globeBasis, globeFlatMix, globeRadius, globeToLocal, groundAt, iconRotation, insideFootprint, latFromMercatorY, lngFromMercatorX, lngLatToUnit, matchesFilter, mercatorMetersPerTile, mercatorX, mercatorY, mercatorZFromAltitude, metersPerPixel, metersPerTile, nextQualityDown, parseGlb, parseGlbAsync, parseGlyphs, parseHash, patchUV, pickBuilding, pickFill, pitchIntent, pixelsPerMeter, placeAlongLine, pointInRing, qualityFor, qualityProfile, raySphere, resolveTemplate, roundRing, sdfFromAlpha, shapeText, splitBucketKey, splitByGround, splitPolygons, styleWithTheme, tileOriginMeters, tileUrl, toLngLat, unitToLngLat, worldSize };

package/dist/osmgl.d.ts

@@ -4350,6 +4350,14 @@ interface QualityProfile {
     simpleGeometry: boolean;
 }
 declare const qualityProfile: (name: QualityName) => QualityProfile;
+/**
+ * Класс GPU по строке рендерера.
+ *
+ * `unknown` — не признак слабости, а честное «не знаем»: Safari отдаёт всем одну и ту же строку,
+ * Firefox её огрубляет, а Tor и Brave в строгом режиме не отдают вовсе. Поэтому неизвестность НЕ
+ * должна ничего решать — она просто оставляет вывод за остальными признаками.
+ */
+type GpuClass = 'software' | 'weak' | 'strong' | 'unknown';
 /** То, из чего делается вывод. Вынесено в аргумент, чтобы это можно было проверить тестом. */
 interface DeviceHints {
     /** Число логических ядер (`navigator.hardwareConcurrency`). */
@@ -4359,7 +4367,22 @@ interface DeviceHints {
     /** Мобильное устройство: грубый указатель или явный признак от браузера. */
     mobile: boolean;
     devicePixelRatio: number;
+    /** Класс видеокарты по строке рендерера, если её удалось прочитать. */
+    gpu?: GpuClass;
 }
+/**
+ * Класс GPU по строке `UNMASKED_RENDERER_WEBGL`.
+ *
+ * Ровно тот же приём, на котором стоит `detect-gpu`: строка рендерера — единственное, что браузер
+ * говорит о видеокарте, не заставляя ничего рисовать. Полноценная база моделей с замерами (как у
+ * `detect-gpu`) сюда не поместится и устареет, поэтому распознаём только то, что решает исход:
+ * программный растеризатор, заведомо слабое встроенное видео и заведомо сильные дискретные чипы.
+ * Всё остальное — `unknown`, и решают ядра с памятью.
+ *
+ * Мерить бенчмарком на старте по-прежнему нельзя: это сотни миллисекунд ровно там, где важна первая
+ * отрисовка. Строка бесплатна.
+ */
+declare function classifyRenderer(renderer: string): GpuClass;
 /**
  * Профиль по признакам устройства.
  *
@@ -4381,6 +4404,101 @@ declare function deviceHints(): DeviceHints;
 declare function clampPixelRatio(cssWidth: number, cssHeight: number, devicePixelRatio: number, profile: QualityProfile): number;
 /** Следующий профиль вниз или null, если ниже некуда. */
 declare function nextQualityDown(name: QualityName): QualityName | null;
+/** Решение контроллера: на какую ступень перейти и в какую сторону. */
+interface QualityChange {
+    to: QualityName;
+    direction: 'up' | 'down';
+    /** Доля тяжёлых кадров, на которой решение принято, — для сообщения в консоль. */
+    share: number;
+}
+/**
+ * Кто решает, менять ли ступень качества.
+ *
+ * ЗАЧЕМ ОТДЕЛЬНЫМ КЛАССОМ. Логика тут вся в состоянии — окно кадров, счётчики попыток, прогрев, —
+ * и ошибка в ней не падает, а проявляется миганием теней у пользователя. Отдельно её видно и можно
+ * проверить тестом, подавая кадры прямо (см. `tests/quality.test.mjs`).
+ *
+ * УСТРОЙСТВО. Вниз — быстро и по доле тяжёлых кадров: тормоза видно сразу. Вверх — медленно, с
+ * ГИСТЕРЕЗИСОМ (порог подъёма на порядок ниже порога спуска) и с ХРАПОВИКОМ: каждая неудачная
+ * попытка удваивает требуемое время спокойствия, а после второй ступень закрывается насовсем.
+ * Именно храповик даёт главное свойство — качели ГАРАНТИРОВАННО затухают, а не ходят вечно.
+ *
+ * Так же устроены адаптивные масштабы разрешения в игровых движках: гистерезис против дребезга и
+ * ограниченное число проб вверх, чтобы «подкачка» качества не стала заметной сама по себе.
+ */
+declare class QualityGovernor {
+    private current;
+    private ceiling;
+    /** Кадр дольше этого — тяжёлый. */
+    private readonly slowMs;
+    /** Кадр дольше этого весит втрое: сотня миллисекунд — это не «немного не успели». */
+    private readonly verySlowMs;
+    private ring;
+    private at;
+    private sum;
+    private filled;
+    /** Кадров подряд на текущей ступени (после прогрева). */
+    private steady;
+    private warmup;
+    /** Неудачные попытки подъёма на ступень: имя → сколько раз сорвались. */
+    private attempts;
+    /** Пришли ли мы на текущую ступень подъёмом — только такой срыв считается неудачей. */
+    private arrivedByUp;
+    /** Последние измерения — запасная оценка шага развёртки. См. [[threshold]]. */
+    private recent;
+    private recentAt;
+    private recentFilled;
+    /** Измеренный шаг развёртки экрана, мс. Ноль — не измерен. */
+    private refreshMs;
+    constructor(current: QualityName, ceiling: QualityName, 
+    /** Кадр дольше этого — тяжёлый. */
+    slowMs: number, 
+    /** Кадр дольше этого весит втрое: сотня миллисекунд — это не «немного не успели». */
+    verySlowMs: number);
+    /** Потолок, до которого разрешено подниматься сейчас. Опускается сам, когда ступень не даётся. */
+    get limit(): QualityName;
+    /** Сменили ступень снаружи (`setQuality`) — начать наблюдение заново. */
+    reset(current: QualityName, ceiling: QualityName): void;
+    /**
+     * Очередной кадр. `busy` — едут ли тайлы: пока едут, кадры не считаются вовсе.
+     *
+     * Зум и панорама всегда дают всплеск — приезжают и разбираются новые тайлы, — и на нём порог
+     * набирался за пару секунд у любой карты. Мерить надо УСТОЯВШУЮСЯ стоимость, а не стоимость
+     * загрузки.
+     */
+    frame(frameMs: number, busy: boolean): QualityChange | null;
+    /**
+     * Порог «тяжёлого кадра» с поправкой на ЭКРАН.
+     *
+     * Мерой служит интервал между кадрами, а порог был жёсткий — 32 мс, «медленнее тридцати в
+     * секунду». Но тридцать в секунду бывает и потолком САМОГО экрана: развёртка 30 Гц, режим
+     * энергосбережения, композитор, ограничивший вкладку. Там интервал ровно 33 мс не потому, что
+     * карта не успевает, а потому, что чаще показывать некуда, — и здоровая машина уезжала до
+     * `minimal`, а на границе порога ещё и раскачивалась. Проверено: на широком окне шаг оказался
+     * ровно 33 мс, и профиль сходил на три ступени за шесть секунд.
+     *
+     * Шаг развёртки берём ИЗМЕРЕННЫЙ (`setRefresh`), а не выведенный из тех же кадров. Вывод по
+     * минимуму здесь принципиально неоднозначен: машина, ровно пригвождённая к 40 мс, неотличима от
+     * экрана на 25 Гц — в обоих случаях все интервалы одинаковы. Разводит их только замер на ПУСТЫХ
+     * кадрах в начале жизни карты, когда рисовать ещё нечего и частота кадров равна развёртке.
+     *
+     * Минимум по недавним кадрам остаётся запасным вариантом — на случай, если замер не удался.
+     * Порог ниже исходного не опускается: на экране 120 Гц требовать от карты 120 кадров незачем.
+     */
+    private threshold;
+    /**
+     * Сообщить измеренный шаг развёртки экрана (мс между кадрами при пустой сцене).
+     *
+     * Заведомо неправдоподобное игнорируем: быстрее 240 Гц экранов у нас нет, а всё, что медленнее
+     * 20 кадров в секунду, — это уже не развёртка, а неудавшийся замер.
+     */
+    setRefresh(ms: number): void;
+    private down;
+    private up;
+    private moveTo;
+    /** Забыть накопленное: после смены ступени прежние кадры относятся к другому профилю. */
+    private restart;
+}
 
 /**
  * Кусок предка, приходящийся на этот тайл: сдвиг и масштаб текстурной
@@ -5534,16 +5652,8 @@ declare class Map$1 extends Evented<MapEvents> {
      * собой заменяли, — см. `setObjects3DEnabled`.
      */
     private objects3dEnabled;
-    /** Кадры подряд, не уложившиеся в бюджет, — счётчик для понижения профиля. */
-    /** Кольцо весов кадров окна: 0 — уложился, 1 — тяжёлый, 3 — очень тяжёлый. */
-    private readonly frameRing;
-    private ringAt;
-    private ringSum;
-    private ringFilled;
-    /** Кадров на текущей ступени — чтобы не проситься выше сразу после смены. */
-    private steadyFrames;
-    /** Профиль, выбранный по железу: выше него не поднимаемся никогда. */
-    private qualityCeiling;
+    /** Кто решает, менять ли ступень качества. Вся логика окна и храповика — в нём. */
+    private governor;
     /** Время прошлого кадра и сколько кадров идёт подряд — для честного замера. */
     private lastFrameAt;
     private continuousFrames;
@@ -5554,6 +5664,19 @@ declare class Map$1 extends Evented<MapEvents> {
     /** Слепок прошлого набора этажей — чтобы не слать событие каждый кадр. */
     private lastIndoorKey;
     constructor(options: MapOptions);
+    /**
+     * Замерить шаг развёртки экрана — по пустым кадрам в самом начале жизни карты.
+     *
+     * Автоснижение судит о тормозах по интервалу между кадрами, и без этого числа сравнивать его не
+     * с чем. Отдельный замер нужен потому, что по рабочим кадрам развёртку не вычислить: экран на
+     * 30 Гц и машина, ровно вдвое не успевающая на 60 Гц, дают одинаковые 33 мс. А вот пока рисовать
+     * нечего — тайлы ещё едут, сцена пуста, — частота кадров равна развёртке, и это тот единственный
+     * момент, когда её видно.
+     *
+     * Обработчик НИЧЕГО не рисует: он только запоминает отметки времени. Своих кадров он не заказывает
+     * сверх этих двенадцати и заканчивается за пятую долю секунды.
+     */
+    private measureRefresh;
     private initGL;
     private initSource;
     /** Имя источника размещений 3D-объектов (если они вообще включены). */
@@ -5826,10 +5949,9 @@ declare class Map$1 extends Evented<MapEvents> {
      *
      * Определение по признакам устройства ошибается в обе стороны: телефон с
      * восемью ядрами может нести слабый GPU, а браузер — врать про плотность.
-     * Поэтому профиль ещё и проверяется делом. Понижаем только ПОДРЯД идущие
-     * тяжёлые кадры: одиночные всплески даёт и сборка мусора, и подъезд тайлов.
-     * Обратно вверх не поднимаемся — качели «плохо → хорошо → плохо» заметнее,
-     * чем стабильно работающая карта.
+     * Поэтому профиль ещё и проверяется делом. Решение принимает `QualityGovernor` — там же и
+     * защита от качелей: гистерезис, прогрев после смены и храповик на попытки подъёма. Здесь
+     * остаётся только применить решение.
      *
      * ДВА ОГРАНИЧЕНИЯ, без которых от этого механизма больше вреда, чем пользы.
      *
@@ -5837,17 +5959,15 @@ declare class Map$1 extends Evented<MapEvents> {
      * геометрии. Разрешение пользователь видит сразу и целиком: подписи и значки после понижения
      * рисуются в буфер меньше экрана, браузер растягивает его обратно, и карта становится мыльной.
      * Упрощение геометрии отнимает у поверхностей фаску, подъём и скругление — приподнятый газон
-     * становится плоским пятном. Обратно вверх мы не поднимаемся, значит и то и другое осталось бы
-     * навсегда. Режем РАБОТУ (детализацию, тени, число тайлов и воркеров) — её потерю видно куда
-     * меньше. Так же поступают MapLibre и Mapbox: `pixelRatio` у них не адаптивный.
+     * становится плоским пятном. Обратно эти две вещи не поднимаются, значит и то и другое осталось
+     * бы навсегда. Режем РАБОТУ (детализацию, тени, число тайлов и воркеров) — её потерю видно куда
+     * меньше, и она обратима. Так же поступают MapLibre и Mapbox: `pixelRatio` у них не адаптивный.
      *
      * Второе: пока едут тайлы, кадры не считаются вовсе. Зум и панорама всегда
      * дают всплеск — приезжают и разбираются новые тайлы, — и на нём порог
      * набирался за пару секунд у любой карты. Мерить надо УСТОЯВШУЮСЯ стоимость,
      * а не стоимость загрузки.
      */
-    /** Забыть накопленное: после смены ступени прежние кадры относятся к другому профилю. */
-    private resetFrameWindow;
     private checkFrameBudget;
     getShadows(): ShadowSettings;
     /**
@@ -5985,4 +6105,4 @@ declare class Map$1 extends Evented<MapEvents> {
     destroy(): void;
 }
 
-export { type AnimationOptions, AssetLoader, type AssetLoaderOptions, BASE_SOURCE, BUILDING_HEIGHT_SCALE, BUILDING_POS_SCALE, BUILDING_VERTEX_STRIDE, type BuildingHit, type BuildingsMesh, CITY_STYLE, type CameraOptions, Circle, type CircleOptions, type CoverOptions, DEFAULT_ICONS, DEFAULT_LIGHT, DEFAULT_SHADOWS, DEFAULT_SKY, DEFAULT_STYLE, DepthTarget, type DeviceHints, EARTH_CIRCUMFERENCE, FILL_VERTEX_STRIDE, type Filter, type FitBoundsOptions, type FitViewport, type FogPlanes, GLOBE_MAX_PITCH, GLOBE_ZOOM_MAX, GLOBE_ZOOM_MIN, GLYPH_BORDER, GLYPH_SIZE, GROUND_SCALE, GeomType, type GestureOptions, type Glyph, type GlyphMetric, GlyphSource, GroundArrows, IconSource, IndoorMask, type Interpolated, LEVEL_LIMIT, LINE_VERTEX_STRIDE, type LayerPlan, LayerRenderer, type LightSpec, type LinePlacement, type LngLat, LngLatBounds, type LngLatLike, MAX_LATITUDE, MODEL_VERTEX_STRIDE, Map$1 as Map, type MapEvents, MapObject, type MapObjectOptions, type MapOptions, Marker, type MarkerOptions, Model, ModelLayer, type ModelMesh, type ModelOptions, type ModelPrimitive, ObjectManager, type ObjectPaint, type ObjectPart, type Padding, type PlacedGlyph, type PlacedSymbol, Polygon, type PolygonOptions, Polyline, type PolylineOptions, type PolylineSegment, Popup, type PopupOptions, type Projection, type QualityName, type QualityProfile, RELIEF_STYLE, RUNTIME_FILL_STRIDE, RUNTIME_LINE_STRIDE, RasterSource, type RasterSourceOptions, RasterTile, type RoundOptions, type RuntimeMesh, SDF_EDGE, SDF_PX, SOFT_STYLE, SPLIT_SEP, SURFACE_CUT_BLEED, SURFACE_LEVEL_SCALE, SURFACE_VERTEX_STRIDE, type ScreenPoint$1 as ScreenPoint, SdfAtlas, type ShadowSettings, type SkySpec, Style, type StyleLayerSpec, type StyleSpec, type SymbolHit, SymbolRenderer, THEMES, TILE_SIZE, type ThemeSpec, TileID, Transform, VectorTile, VectorTileFeature, VectorTileLayer, abbreviateStreet, addGround, altitudeFromMercatorZ, applyTheme, arrowLabelOffset, arrowVertices, buildRuntimeFill, buildRuntimeLine, cameraForBounds, circumferenceAtLatitude, clampLat, clampPixelRatio, clipLineToRect, coordinateDigits, coveringTiles, createGround, Map$1 as default, deviceHints, distToSegment, evaluateColor, evaluateNumber, extractFeature, featureLevel, fillFootprint, fogPlanes, footprintOf, formatHash, generateBuildings, generateFill, generateLine, generateSurface, generateSymbols, globeBasis, globeFlatMix, globeRadius, globeToLocal, groundAt, iconRotation, insideFootprint, latFromMercatorY, lngFromMercatorX, lngLatToUnit, matchesFilter, mercatorMetersPerTile, mercatorX, mercatorY, mercatorZFromAltitude, metersPerPixel, metersPerTile, nextQualityDown, parseGlb, parseGlbAsync, parseGlyphs, parseHash, patchUV, pickBuilding, pickFill, pitchIntent, pixelsPerMeter, placeAlongLine, pointInRing, qualityFor, qualityProfile, raySphere, resolveTemplate, roundRing, sdfFromAlpha, shapeText, splitBucketKey, splitByGround, splitPolygons, styleWithTheme, tileOriginMeters, tileUrl, toLngLat, unitToLngLat, worldSize };
+export { type AnimationOptions, AssetLoader, type AssetLoaderOptions, BASE_SOURCE, BUILDING_HEIGHT_SCALE, BUILDING_POS_SCALE, BUILDING_VERTEX_STRIDE, type BuildingHit, type BuildingsMesh, CITY_STYLE, type CameraOptions, Circle, type CircleOptions, type CoverOptions, DEFAULT_ICONS, DEFAULT_LIGHT, DEFAULT_SHADOWS, DEFAULT_SKY, DEFAULT_STYLE, DepthTarget, type DeviceHints, EARTH_CIRCUMFERENCE, FILL_VERTEX_STRIDE, type Filter, type FitBoundsOptions, type FitViewport, type FogPlanes, GLOBE_MAX_PITCH, GLOBE_ZOOM_MAX, GLOBE_ZOOM_MIN, GLYPH_BORDER, GLYPH_SIZE, GROUND_SCALE, GeomType, type GestureOptions, type Glyph, type GlyphMetric, GlyphSource, type GpuClass, GroundArrows, IconSource, IndoorMask, type Interpolated, LEVEL_LIMIT, LINE_VERTEX_STRIDE, type LayerPlan, LayerRenderer, type LightSpec, type LinePlacement, type LngLat, LngLatBounds, type LngLatLike, MAX_LATITUDE, MODEL_VERTEX_STRIDE, Map$1 as Map, type MapEvents, MapObject, type MapObjectOptions, type MapOptions, Marker, type MarkerOptions, Model, ModelLayer, type ModelMesh, type ModelOptions, type ModelPrimitive, ObjectManager, type ObjectPaint, type ObjectPart, type Padding, type PlacedGlyph, type PlacedSymbol, Polygon, type PolygonOptions, Polyline, type PolylineOptions, type PolylineSegment, Popup, type PopupOptions, type Projection, type QualityChange, QualityGovernor, type QualityName, type QualityProfile, RELIEF_STYLE, RUNTIME_FILL_STRIDE, RUNTIME_LINE_STRIDE, RasterSource, type RasterSourceOptions, RasterTile, type RoundOptions, type RuntimeMesh, SDF_EDGE, SDF_PX, SOFT_STYLE, SPLIT_SEP, SURFACE_CUT_BLEED, SURFACE_LEVEL_SCALE, SURFACE_VERTEX_STRIDE, type ScreenPoint$1 as ScreenPoint, SdfAtlas, type ShadowSettings, type SkySpec, Style, type StyleLayerSpec, type StyleSpec, type SymbolHit, SymbolRenderer, THEMES, TILE_SIZE, type ThemeSpec, TileID, Transform, VectorTile, VectorTileFeature, VectorTileLayer, abbreviateStreet, addGround, altitudeFromMercatorZ, applyTheme, arrowLabelOffset, arrowVertices, buildRuntimeFill, buildRuntimeLine, cameraForBounds, circumferenceAtLatitude, clampLat, clampPixelRatio, classifyRenderer, clipLineToRect, coordinateDigits, coveringTiles, createGround, Map$1 as default, deviceHints, distToSegment, evaluateColor, evaluateNumber, extractFeature, featureLevel, fillFootprint, fogPlanes, footprintOf, formatHash, generateBuildings, generateFill, generateLine, generateSurface, generateSymbols, globeBasis, globeFlatMix, globeRadius, globeToLocal, groundAt, iconRotation, insideFootprint, latFromMercatorY, lngFromMercatorX, lngLatToUnit, matchesFilter, mercatorMetersPerTile, mercatorX, mercatorY, mercatorZFromAltitude, metersPerPixel, metersPerTile, nextQualityDown, parseGlb, parseGlbAsync, parseGlyphs, parseHash, patchUV, pickBuilding, pickFill, pitchIntent, pixelsPerMeter, placeAlongLine, pointInRing, qualityFor, qualityProfile, raySphere, resolveTemplate, roundRing, sdfFromAlpha, shapeText, splitBucketKey, splitByGround, splitPolygons, styleWithTheme, tileOriginMeters, tileUrl, toLngLat, unitToLngLat, worldSize };